cs-doc-api

cs-doc-api

Required reading at startup

Before starting any judgment or action, first run CodeStable preflight: read .codestable/attention.md；if missing, first cs-onboard；do not read external AI entry points as a substitute (see .codestable/reference/execution-conventions.md）。

doc-tutorial teaches you "how to use X to do Y"; doc-api tells you "what each part of X looks like and how to configure it."

A mistake in doc-tutorial may be unclear expression, but a mistake in doc-api is simply wrong—the information source is the source code itself; types / default values / signatures all have a single correct answer.Core rules: do not guess, do not copy and rename, read the source code independently for each entry。

Comparison with doc-tutorial

	doc-tutorial	doc-api
Nature	Task-oriented (Tutorial / How-to)	Reference-oriented (Reference)
Answer	"How to use X to achieve a certain goal"	"What each part of X looks like and how to configure it"
Granularity	One feature / one scenario per article	One entry per article
Information source	Solution doc + user knowledge	The source code itself(types / comments / default values)
Order of magnitude	A few to a dozen or so articles	Dozens to hundreds of articles

Complementary: doc-tutorial references doc-api for detailed reference ("for complete props see xxx"), and doc-api's "related entries" link back to doc-tutorial.

"Entry"

Project type	Entry granularity
UI component library	One component = one entry
Utility function library	One module or function family = one entry
API Client	One endpoint family = one entry
CLI tool	One subcommand = one entry

Confirm the entry granularity during the initialization phase and keep it consistent afterward—if the granularity keeps changing, the list and search will both become chaotic.

Paths involved

doc-api artifactsNot under .codestable/ under—API reference is a publishable artifact intended for external readers.

Entry documentation → docs/api/{slug}.md
Entry list → docs/api/manifest.yaml

docs/api/ is the default convention; if the project already has another convention (reference/ / components/), follow the project—confirm before starting.

manifest / template / source code extraction

Reference materials are in the same directory reference.md：

manifest.yaml Complete format and status semantics
Entry documentation frontmatter and body template
Source code extraction checklist (interface signatures, default values, export methods, etc.)

The body of this skill retains only process constraints:doc-api uses source code as the source of truth, does not guess, and does not copy the previous entry and rename it。

Workflow

Phase 1: Initialization—scan and list

Confirm project type + entry granularity + output path
Scan the source code directory—read the file structure under source_root identify public exports and group them logically
Generate manifest.yaml—all entries initially status: pending；after writing to disk, validate-yaml.py --file docs/api/manifest.yaml --yaml-only validate; show to the user for review
User confirms the scope—can be marked skipped(internal implementation) / adjust category / merge or split

Phase 2: Generation

Mode A: Single-entry mode

Suitable for 1-3 entries or a first trial run to confirm quality.

Select entry → read source_files → generate per template → user review → write to disk → validate-yaml.py --file {路径} --require doc_type --require entry --require status → manifest corresponding entry status: current

Mode B: Batch mode

Suitable for a large number in the list pending。

produce samples first—select 2-3 representative entries from the list (different categories) and go through "read source code → extract → generate per template" and write to disk, with status first draft(do not go directly into current—in batch mode the samples are "style reference samples" and are moved to current together after the overall review)
User confirms quality standard—review these 2-3 pieces to confirm template / level of detail / style.This step cannot be skipped—all 50 pieces would be written in vain just because the style the user wants is different
Batch generation—remaining pending go through "read source code → extract → generate" one by one, can use Task agent in parallel; each entry status: draft
overall review—after batch completion show an overview (number of entries / number skipped / number pending confirmation); before review first validate-yaml.py --dir docs/api --require doc_type --require entry --require status batch-validate Markdown docs (directory mode does not scan by default manifest.yaml）
confirm and finalize—after user confirmation, change both the samples and batch outputs to status: current

Batch mode hard rules：

Each entry reads source code independently—even in batch mode, copying the previous one and renaming is not allowed. Two interfaces that look very similar often have subtle differences
Sample confirmation cannot be skipped
Source structure is special (dynamic export / code generation), temporarily mark skipped add note—guessed documentation is more harmful than no documentation

Phase 3: Incremental update

Sync documentation after code changes. Choose any of three entry points:

search-yaml.py search status=outdated—architecture check or those already marked by the last update
Compare manifest.yaml in last_scanned source files changed after
search-yaml.py --sort-by last_reviewed --order asc proactively review in order of longest time since review

re-read source code → compare with existing docs → incrementally update changed parts → validate-yaml.py validate → status: current + last_reviewed same day.

Relationship with other workflows

Source	Relationship
`cs-feat-accept`	After acceptance, add/modify public library interfaces → push "Need to update doc-api?"
`cs-doc-tutorial`	doc-tutorial references doc-api for detailed reference; doc-api "related entries" link back to doc-tutorial
`cs-feat-design`	Section 2 of the plan can serve as a supplementary information source for doc-api (but source code prevails）
`cs-keep`	When doc-api "notes" overlap with compound deposits, cross-reference rather than duplicate

Exit conditions

Phase 1: manifest.yaml has been written to disk + user has confirmed scope (including skipped reasons) + granularity and output path have been confirmed

Phase 2 single entry: entry generated per template + frontmatter complete + API reference section information comes from source code extraction (not fabricated) + user confirmation + manifest updated

Phase 2 batch: Sample (2-3 pieces) has been confirmed by the user + all pending items have been generated or marked skipped + the user has done an overall review + all manifest item statuses have been synced

Phase 3: All outdated items have been updated or confirmed as not needing updates + manifest has no remaining outdated (unless the user explicitly defers)

Common pitfalls

Writing docs without scanning the manifest—may miss or duplicate
Writing API reference without reading the source—doc-api's core value is accurately reflecting the source
Copying the previous item and renaming it—will inevitably miss subtle differences
Skipping sample confirmation in batch mode—all 50 pieces wasted
Writing spec information (invariants / test constraints) into doc-api—belongs to .codestable/
doc-api and doc-tutorial content highly overlap—one of them has the wrong positioning
manifest.yaml directly deleting lines—change status: skipped and write note
Source interface does not exist but is written in the docs—take the source as the source of truth, do not fabricate