Developer Reference Starlight section

Status: Open — Phase 1, confirmation needed (URL structure, sidebar config)

Problem

Internal developer docs (behavioral specs, ADRs, architecture notes, code tour) are not browsable on the live site. The committed design material is split between roadmap pages and code-level comments, so there is no single browsable developer-reference section in Starlight.

Goal

All internal docs browsable at jackin.tailrocks.com/internal/. One unified site for both user documentation and developer reference.

What gets created

docs/src/content/docs/internal/
  index.mdx              ← "Developer Reference" landing page
  architecture.mdx       ← high-level module architecture
  code-tour.mdx          ← stub: key call chains (load, console launch, hardline)
  specs/                 ← behavioral + feature specs (runtime-launch, op-picker, ...)
  decisions/             ← ADRs (ADR-001 through ADR-003, ...)

astro.config.ts sidebar addition

{
  label: 'Developer Reference',
  collapsed: true,
  items: [
    { label: 'Architecture', slug: 'internal/architecture' },
    { label: 'Code Tour', slug: 'internal/code-tour' },
    { autogenerate: { directory: 'internal/decisions' } },
    { autogenerate: { directory: 'internal/specs' } },
  ]
}

Steps

1. Create the directory structure with stub MDX files (frontmatter + one paragraph).
2. Add the sidebar group to docs/astro.config.ts.
3. Verify bun run build passes.
4. Verify bun run check:links:fresh still passes.

What needs confirmation

• The URL prefix (/internal/) — confirm this is the right prefix.
• collapsed: true for the sidebar group — confirm this is the right UX default.

Caveats

Draft MDX pages with broken links will fail the docs-link-check CI gate. Use only working links (or no links) in placeholder pages.