sv-cli-doc-site

Imported from ian0x-S2/sv-cli-doc-site (AGENTS.md). Install upstream with npx skills add ian0x-S2/sv-cli-doc-site. Copyright stays with the author.

AGENTS.md

sv-doc is a deterministic CLI for reading and searching Markdown documentation from the terminal. It is designed for fast, scriptable access to a docs tree, especially for AI agents and automation workflows.

Product Specification

Product Definition

• sv-doc is a local-first documentation CLI.
• It reads Markdown from a documentation tree and exposes it through deterministic terminal commands.
• It is optimized for workflows where documentation must stay readable by humans and reliably consumable by agents.
• The site exists to explain the product, demonstrate the protocol, and present the same documentation in a human-friendly format.

Target Audience

• AI agents that need stable, low-noise access to documentation.
• Developers building automation around local Markdown docs.
• Teams that want one documentation source for both rendered sites and raw file access.
• Svelte and SvelteKit users browsing the docs through the site while retaining access to source Markdown.

Core Value Proposition

• Single source of truth: documentation lives in /docs as Markdown.
• Dual delivery model: humans read rendered docs, agents read raw Markdown.
• Deterministic output: results are plain text, sorted, and free of decorative terminal formatting.
• Scriptable workflow: search, inspect, extract, and retrieve content in small steps.
• Local-first operation: documentation can be read from the repository, an explicit docs root, or an embedded standalone build.

Project Context

• The site documentation system follows a Unix-style philosophy: simple, composable, and readable by both humans and machines.
• The product is presented as a protocol-first documentation tool, not as a generic marketing site.
• The site should explain how the CLI works, why the docs model matters, and how the same content serves both human readers and automation.

Goal

Serve the same documentation in two formats:

Humans -> rendered site using mdsvex

Agents -> raw Markdown files

Both formats come from the same source files.

Principles

Single source of truth: documentation lives in /docs as Markdown.

Human-friendly: rendered with mdsvex for the documentation website.

Agent-friendly: raw Markdown remains accessible for programmatic reading.

Small, modular files: each file represents a single concept.

Unix philosophy: simple files, predictable structure, easy to search.

Supported Usage Modes

1. Run from source

Use this while developing inside the repository:

bun ./index.ts <command> [args]

Example:

bun ./index.ts list

2. Install as a linked CLI

Use this if you want to call sv-doc from anywhere on your machine during development:

bun install
bun link

Then run:

sv-doc list

3. Build a standalone executable

Use this when you want to run the CLI on another machine without the repository:

bun run build

Build all supported targets:

bun run build:all

The standalone executable must include the Markdown files from docs/, so it can work even when the docs folder is not present on disk.

Documentation Source Resolution

sv-doc chooses its documentation source in this order:

1. If DOCS_ROOT is set, use that directory.
2. Otherwise, if ./docs exists, use that directory.
3. Otherwise, use the docs embedded in a standalone executable.

This behavior must be documented consistently in the site and in repository metadata.

Required Path Rule

When passing a file path to sv-doc, the path must be relative to the documentation root.

Do not include docs/ at the beginning.

Correct:

sv-doc get svelte/runes/state/state.md

Incorrect:

sv-doc get docs/svelte/runes/state/state.md

This rule is mandatory and should be surfaced prominently on the docs landing page.

Recommended Usage Pattern

If you are exploring documentation, use the CLI in this order:

1. Find relevant files with search --paths.
2. Inspect a file structure with headings.
3. Read one section with section.
4. Read the full file with get only when needed.

Example:

sv-doc search "reactive state" --paths
sv-doc headings svelte/runes/state/state.md
sv-doc section svelte/runes/state/state.md "summary"
sv-doc get svelte/runes/state/state.md

Command Reference

list

Lists all markdown files found in the documentation root, sorted lexicographically.

sv-doc list

search <query> [--limit <n>] [--paths]

Performs a case-insensitive search across all markdown files.

• --limit <n> limits result count. Default: 20.
• --paths returns only unique matching file paths.

sv-doc search "form actions" --paths

headings <path>

Returns all markdown headings from the specified file.

sv-doc headings sveltekit/forms/form-actions.md

section <path> <heading> [--follow-related]

Extracts the content under a specific heading.

• Heading matches are case-insensitive.
• It can match the heading title or the full heading line.
• It includes nested sub-headings until the next heading of the same or higher level.
• --follow-related resolves and prints linked files listed under the related section.

sv-doc section sveltekit/load/load.md "streaming"

outline [dir]

Maps all markdown files under an optional subdirectory, showing their headings inline.

sv-doc outline svelte/runes/state

get <path>

Returns the full raw markdown content of the file.

sv-doc get sveltekit/load/load.md

--help, -h, help [command]

Shows general help or command-specific help.

sv-doc --help
sv-doc section --help

Output And Error Contract

• Standard output contains plain text or raw Markdown.
• Errors are written to stderr.
• Exit code 0 indicates success.
• Exit code 1 indicates an operational error such as file not found or heading not found.
• Output should remain deterministic, sorted where applicable, and free of terminal decoration.

Site Content Contract

Home Page Must Communicate

• What sv-doc is.
• Who it is for.
• Why a dual human-and-agent docs model matters.
• That Markdown in /docs is the single source of truth.
• That the product is local-first, deterministic, and scriptable.

Docs Landing Page Must Communicate

• All supported usage modes.
• The required relative-path rule.
• The recommended command workflow.
• The core commands and what each returns.
• DOCS_ROOT behavior.
• Standalone distribution behavior.
• Exit-code and output guarantees.

Messaging Rules

• Keep the tone technical, objective, and compact.
• Prefer explicit product language over clever or ambiguous phrasing.
• Use humans or human readers instead of vague labels.
• Do not market unsupported capabilities.
• Keep copy consistent with actual CLI behavior.

UI / UX Direction — Micro Design System

Design Principles

Content First

Documentation is the primary focus. The layout is skeletal, serving only to frame the content without visual noise.

Micro-Scale Precision

• Typography: Smaller base scales (labels at 9px-11px).
• Density: High information density with minimal whitespace padding.
• Monospace Priority: Use font-mono for all functional elements, metadata, and navigation.

Human + Agent Protocol

• Humans: Ultra-minimalist interface with clear hierarchy.
• Agents: Explicit "Protocol" labels and direct links to raw Markdown.

Unix Philosophy

• simple
• modular
• minimal visual noise
• functional beauty

Visual Style

Aesthetic

• Technical Minimalism: High-precision borders (0.5px - 1px) with low opacity (10-20%).
• Micro-UI: Compact buttons, small icons (size-3 to size-4), and tight grid layouts.
• Data-Rich: Metadata formatted as system strings (e.g., Status: Production, Est_Read_5M).
• Subtle Glass: Minimal use of backdrop-blur on headers and floating elements.
• Theme: High-contrast Dark/Light mode with a focus on neutral tones and a single primary accent.

Base

• Precision-engineered
• Technical
• Anti-decorative

Visual References

• Vercel (technical parts)
• Linear (compact mode)
• Raycast (overlay and search UI)
• shadcn/ui (skeletal structure)
• Terminal and CLI interfaces

Svelte Documentation

Project documentation is stored locally in /docs.

Docs are organized into small Markdown files by concept.

Example:

docs/
	svelte/
		runes/
			state/
				state.md
				raw-state.md
				state-snapshot.md

Each file describes one concept.

When to Consult Docs

Use the documentation if:

• framework behavior is uncertain
• Svelte or SvelteKit API usage must be verified
• implementation rules are unclear

How to Search Docs

Use sv-doc for high-performance, deterministic lookup.

Find relevant files:

sv-doc search "keyword" --paths

Example:

sv-doc search "state snapshot" --paths

Map available topics:

sv-doc outline

Retrieve specific sections:

sv-doc section svelte/runes/state/state.md "summary"

Load only the relevant sections before retrieving a full file.

Doc Structure

Files may include:

• summary
• rules
• examples
• pitfalls
• related

Prefer summary and rules for core behavior.

Architecture Policy

Pattern: feature-sliced | Framework: Svelte 5 | Styling: utility-first

Layers & Import Direction

app -> features -> entities -> shared (unidirectional, strict)

• Cross-feature imports: FORBIDDEN
• Circular imports: FORBIDDEN
• Cross-slice imports must go through index.ts

Directory Structure

src/
├── routes/ # load functions, actions — no domain logic
├── app/ # providers, router, global styles
├── features/<slice>/
│   ├── ui/ # components
│   ├── api/ # external I/O and API clients — called by load functions
│   └── index.ts # public API (required)
├── entities/<slice>/
│   ├── model/ # domain logic, validators, value objects (no reactive state)
│   ├── api/ # data access, response mapping
│   └── index.ts # public API (required)
└── shared/
		├── ui-kit/ # primitives
		├── api/ # base fetch only — no domain requests
		├── lib/ # pure utils
		└── types/ # global types

File Conventions

• Naming: kebab-case for files
• Inline magic numbers: extract to named constants in *.constants.ts
• Errors must be typed: no throwing raw strings
• Boolean variables must use is, has, or can prefixes
• Barrel exports are required only at feature and entity roots
• No default exports on utilities

Component Rules

• No data fetching in components — receive data via props or load functions
• No business logic in components
• Extract to *.svelte.ts when script blocks exceed 25 lines or logic repeats across two or more components
• Extract to a new component when a template has more than two logical sections
• Max props: 10
• No prop drilling beyond depth 2
• Prefer composition over configuration

Svelte 5 Runes

• $state -> local reactive state
• $derived -> computed values
• $effect -> side effects only
• $props -> component interface
• $bindable -> explicit two-way binding, used sparingly
• No legacy stores for local state

State & Data Flow

route (load fn) -> features/api (use case) -> entities/api (data access) -> entities/model (domain type)

• Side effects are allowed only in features/api and entities/api
• API errors must be mapped to domain types before reaching the UI
• Every async operation requires loading and error state

Forbidden

• Component fetching data directly
• Reactive state ($state) in entities
• Domain logic in features/api
• Raw API responses leaking to UI
• any type (use unknown plus narrowing)
• Type assertions (as) except at data boundaries