doc-reference-public-api

Packet · {{ repo }} · reference/public-api.md

1. Objective

Produce {{ docs_root }}/reference/public-api.md: one H3 per exported symbol for the top 30 public exports of {{ repo }}, each with a fenced code block that quotes the symbol's signature verbatim, a one-sentence description, and a `path:LOC` citation. When {{ repo }} is not a CLI, append an ## HTTP H2 rendered from route_map at the bottom of the file.

2. Scope

• Create: {{ docs_root }}/reference/public-api.md
• Do not touch: any other file under {{ docs_root }}/, any source file in the repo, .context.md, .prefetch.md, or any .packets/*.md other than this one. In particular, do not write to {{ docs_root }}/reference/cli.md — the CLI packet owns that file.

3. Input specification

Source	Read how	Cache state
Shared context	Read {{ context_path }}	always first
Prefetch ledger	Read {{ prefetch_path }}	always first
Project profile	{{ context_path }} § Repo profile	cached
Exported symbols (public surface)	{{ prefetch_path }} § exports or mcp__codehub__sql({query: "SELECT name, kind, file_path, start_line FROM nodes WHERE kind IN ('Function','Class','Method') AND name NOT LIKE '\\_%' ORDER BY file_path LIMIT 500"})	cached if digest present
Per-symbol signatures	mcp__codehub__signature({symbol: <id>})	mid-run (only if cache miss)
Per-symbol usage count	mcp__codehub__context({symbol: <id>})	mid-run (only if cache miss)
HTTP route inventory	{{ prefetch_path }} § route_map or mcp__codehub__route_map({repo: "{{ repo }}"})	cached if digest present
Source fallback for missing signatures	Read <file> at start_line..start_line+20	mid-run

4. Process

1. Read {{ context_path }} and Read {{ prefetch_path }}. Confirm {{ repo }} profile; check project_profile.entry_points for the CLI flag.
2. Pull the exported-symbol list from .prefetch.md § exports. If absent, run the sql query in the input spec and cache the digest in this packet's Work log.
3. Filter to symbols whose file path is a barrel (packages/*/src/index.ts, src/index.ts, mod.rs, __init__.py, or equivalent). Keep that subset as the real exports.
4. For the top 30 exports (ordered by inbound relation count if cached, else by file path): fetch signature({symbol: <id>}) and context({symbol: <id>}). Record signature, inbound count, and path:start_line in the Work log. Reuse cached digests wherever .prefetch.md already recorded them.
5. Determine HTTP rendering: if project_profile.entry_points includes a CLI, skip the HTTP section — the CLI packet owns route rendering. Otherwise, read the route_map digest (or call route_map({repo: "{{ repo }}"}) once) and prepare an ## HTTP H2.
6. Draft one H3 per export. Format: ### <symbol-name>, then a fenced code block quoting the signature verbatim, then a one-sentence description, then the `path:LOC` citation on its own line.
7. If rendering HTTP, append ## HTTP as the final H2, with one H3 per route (### METHOD /path), a one-sentence description, and a `path:LOC` citation. Order routes by path, then method.
8. Write {{ docs_root }}/reference/public-api.md with H1 = {{ repo }} · Public API.