docs: refactoring docs

[leandrodamascena]

Closes #36

Area

• cdk — infrastructure, handlers, constructs
• agent — Python runtime / Docker image
• cli — bgagent client
• docs — guides or design sources (docs/guides/, docs/design/)
• tooling — root mise.toml, scripts, CI workflows

Tip: AGENTS.md lists where to edit and which tests to extend.

Summary

Full documentation reorganization and rewrite. Reduction in design docs, restructured Starlight site with new navigation, added mermaid support, and created a proper Quick Start guide.

Why

I kept going back to these docs while building features and every time I had the same experience: I knew the answer was somewhere in the doc, but finding it meant scrolling through walls of text, past resolved debates, past implementation details I could just read in the code.

The docs were trying to do too many jobs at once. Blueprint code examples next to architecture rationale next to Cedar regex patterns next to answered open questions. Tutorial, reference, and implementation all in the same file. The reader had to filter constantly.

The fix is giving each layer its own home:

• Quick Start / User Guide own "how to use" - steps, examples, code you copy-paste
• Design docs own "how it works" - architecture, interfaces, contracts, trade-offs
• Code owns the implementation - file paths, regex patterns, config tables live there

When each layer does one job, the developer can start with the Quick Start, go deeper into design docs when they need the why, and read code when they need the exact how. No layer tries to be the other two.

What changed

Site restructure

• Renamed design/ to architecture/ and user-guide/ to using/ for clearer navigation
• Added getting-started/ section with a dedicated Quick Start page
• Added customizing/ section for prompt engineering guide
• Removed standalone pages that were split into the new structure (Agent-harness, Control-panel, Network-architecture)
• Updated sync script and astro.config.mjs for new structure
• Added remark-mermaid plugin for diagram rendering

Guides rewrite

Doc	What changed
QUICK_START.md	New. Zero-to-first-PR walkthrough in ~30 min.
DEVELOPER_GUIDE.md	Major cut - removed content that moved to Quick Start and User Guide.
USER_GUIDE.md	Restructured around task types, per-repo overrides, webhooks.
PROMPT_GUIDE.md	Condensed. Focused on actionable patterns and anti-patterns.
CONTRIBUTING.md	Updated to match new project structure.
ROADMAP.md	Checklist format for shipped items. Tables by theme for planned items.

Design docs rewrite

Every design doc got the same treatment: mermaid diagrams, intro paragraphs on every section, tables instead of prose, cut implementation details and resolved decisions.

Doc	Before	After	Key changes
ORCHESTRATOR.md	~1,020	~340	Mermaid state machine + sequence diagram. Cut Options A-D, 10 open questions, conceptual TypeScript.
MEMORY.md	~514	~200	Mermaid lifecycle + defense layers. Cut 90-line extraction prompts, implementation status.
API_CONTRACT.md	~671	~310	Endpoint summary table, mermaid webhook auth flow. Cut duplicate JSON examples.
REPO_ONBOARDING.md	~465	~250	Cut Blueprint code examples (overlap with Quick Start). Kept interfaces as reference.
COMPUTE.md	~338	~190	7-option compute comparison table. Mermaid VPC diagram. Cut emoji eval tables.
SECURITY.md	~271	~195	Mermaid policy flow. Prose to tables. Removed implementation patterns.
OBSERVABILITY.md	~294	~165	Mermaid telemetry architecture. Cut SDK reference tables, runbook stubs, control panel.
EVALUATION.md	~249	~130	Mermaid validation pipeline. Cut TypeScript interfaces, report examples.
ARCHITECTURE.md	~262	reduced	Condensed high-level overview.
COST_MODEL.md	minor	minor	Small fixes.
INPUT_GATEWAY.md	minor	minor	Small fixes.

Cross-cutting

• Removed all Iteration 3b/3c/3d/5 references from design docs
• Removed standalone docs that were consolidated: AGENT_HARNESS.md, CONTROL_PANEL.md, NETWORK_ARCHITECTURE.md

[krokoko]

Thank you @leandrodamascena ! Few questions/comments:

• 1. XSS in remark-mermaid plugin

  docs/plugins/remark-mermaid.mjs:8 interpolates node.value directly into HTML
  with no escaping:

  value: <pre class="mermaid">${node.value}</pre>,

  A mermaid code block containing <script>alert('xss')</script>

   would
  
  be rendered as executable HTML. Yes, this is a docs site built from trusted
  
  source files today — but this is a security-focused project ("ABCA agents
  
  execute code with repository access"). The docs should model the security
  
  posture they describe.
  
  Fix: HTML-entity-escape node.value before interpolation, or use a
  
  well-maintained plugin like rehype-mermaid instead.
  

• 2. Unpinned CDN dependency with no SRI

  "import mermaid from
  'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'"

  Three problems:

  • Loose version pin — mermaid@11 resolves to latest 11.x. A breaking minor
    release silently breaks diagrams.
  • No integrity attribute — A compromised jsDelivr CDN injects arbitrary JS into
    the docs site.
  • No crossorigin attribute — Needed for SRI to work.

  For a project whose SECURITY.md discusses "defense in depth" and DNS Firewall,
  shipping an unpinned, unverified third-party script is incongruent.

  Fix: Pin to exact version (e.g., mermaid@11.4.1), add integrity hash, or
  self-host the library.

• 3. Orphaned files not in sidebar

  Two files exist in the rendered output but are unreachable from navigation:

  • using/Introduction.md — A 5-line stub ("Using the platform") with no useful
    content.
  • using/Prerequisites.md — Renamed from user-guide/Prerequisites.md but content
    absorbed into Quick Start.

  These will be deployed, indexable by search engines, and confusing to anyone who
  lands on them.

  Fix: Delete both files, or add a redirect/note pointing to the correct location.

• 4. Source directory naming mismatch

  The source directory is still docs/design/ on disk, but it renders at
  /architecture/. The sync script handles this mapping, but a future contributor
  editing docs/design/COMPUTE.md may not realize it appears as
  /architecture/compute on the site.

  Fix: Either rename the source directory to docs/architecture/ for alignment, or
  add a comment at the top of the sync script explaining the mapping.

• 5. Sidebar slug mismatch — "Customizing" section mixes paths

  label: 'Customizing',
  items: [
  { slug: 'using/repository-onboarding' }, // ← lives under using/
  { slug: 'using/per-repo-overrides' }, // ← lives under using/
  { label: 'Prompt Engineering', slug: 'customizing/prompt-engineering' }, // ←
  lives under customizing/
  ],

  Two of three items under "Customizing" are actually in the using/ URL path. This
  means:

  • Breadcrumbs may show the wrong hierarchy
  • A user navigating via URL structure (/using/repository-onboarding) won't find
    the page in the sidebar's "Using the Platform" section where they'd expect it

  Fix: Either move Repository-onboarding.md and Per-repo-overrides.md to
  customizing/, or put them in the "Using the Platform" sidebar section and keep
  "Customizing" focused on prompt engineering.

• 6. Incomplete anchor route mapping in sync script

  docs/scripts/sync-starlight.mjs maps only 3 USER_GUIDE anchors to the new using/
  structure:

  const userGuideAnchorRoutes = {
  authentication: '/using/authentication',
  'repository-onboarding': '/using/repository-onboarding',
  'task-lifecycle': '/using/task-lifecycle',
  };

  The old USER_GUIDE had many more sections (CLI, REST API, webhooks, tips, task
  types, per-repo config). Any existing link like USER_GUIDE.md#using-the-cli will
  now fall through to /using/overview#using-the-cli, which doesn't resolve.

  Fix: Audit all anchors in the old USER_GUIDE and add mappings for the ones that
  moved to standalone pages.

[krokoko]

Also, I think this will impact the abca-plugin. Since the setup skill walks users through initial deployment, it should point them to the new Quick Start rather than the old user guide introduction

[leandrodamascena]

Thanks @krokoko for the feedback.

1) XSS in remark-mermaid - done

2) CDN pin - done

3) Orphaned files - Deleted. Added cleanup logic in the sync script so they don't regenerate.

4) Source dir naming - Added a comment in the sync script explaining the docs/design/ -> /architecture/ mapping and why we keep the source directory name.

5) Sidebar slug mismatch - Moved Repository-onboarding.md and Per-repo-overrides.md to customizing/. All three items in the Customizing sidebar section now live under the same URL path.

6) Anchor mapping - Added all missing USER_GUIDE anchors (overview, task-types, using-the-cli, using-the-rest-api, webhook-integration, what-the-agent-does, tips-for-being-a-good-citizen, per-repo-overrides, repository-onboarding).

Plugin impact - Good catch. Updated abca-plugin/skills/setup/SKILL.md to point to /getting-started/quick-start/ instead of the old /user-guide/introduction/.