Skip to main content

​
GRACE Documentation Separation: Protocol vs. Implementation

​
The Core Insight

Grace works best when its documentation is physically separated from STRATT (the reference implementation). We learned this through building a standalone docs site that clearly distinguishes four architectural layers: protocol specification (abstract), reference implementation (STRATT, concrete), intelligence layer (Grace agent), and collaboration platform (Choco HQ).

​
The Problem We Faced

Initially, Grace Protocol documentation lived in MERIDIAN (the STRATT docs site). This caused three issues:
  1. Conceptual confusion: Users reading STRATT docs couldn’t tell if they were learning about Grace (the protocol) or STRATT (the implementation). Example: “Is SPEC-01 part of the spec or part of STRATT?”
  2. Version coupling: Changes to Grace docs forced MERIDIAN rebuilds. Changes to STRATT forced Grace readers to wade through implementation details irrelevant to protocol understanding.
  3. Deployment inflexibility: STRATT’s docs site couldn’t deploy independently from Grace docs. They were permanently entangled.

​
What We Did

We created a standalone grace-hq/docs site using Astro + Starlight with these boundaries:
ContentGoes whereAudience
GRACE Protocol (SPEC-01–05)grace.devarno.cloudArchitects, integrators
Grace agent orchestration (8 agents)grace.devarno.cloudDevelopers, operators
STRATT units, CLI commandsstratt.devUnit contributors
Internal links use relative paths (/protocol/overview/). Cross-workspace links use absolute HTTPS URLs (https://stratt.dev/cli/overview/). MERIDIAN’s sidebar redirects protocol readers to grace.devarno.cloud instead of maintaining duplicate content.

​
The Payoff

  • Independent deployment: Grace docs can ship without touching STRATT or vice versa
  • Audience clarity: Protocol readers see only specs; implementation readers see only units
  • Redaction safety: Sensitive data (budgets, internal state) filtered from public Grace docs before publishing, not retrofitted into public site
  • Version honesty: Grace v1.0 and STRATT v2.0 coexist without synthetic version coupling

​
Technical Pattern: Taskset-Gated Workflow

Each documentation migration step was gated behind a build verification:
  1. T1 (Scaffold): Build must succeed before writing content
  2. T2 (Protocol): Link migration must validate before T3 begins
  3. T3 (Assistant): Redaction audit must pass before building
  4. T4 (Architecture): Spec-to-docs accuracy checked before T5
  5. T5 (Cleanup): MERIDIAN must build with zero broken links
  6. T6 (Audit): Zero stubs, zero broken links across both sites before “done”
This prevented the typical docs refactor trap: “We’ll fix the broken links later.”

​
Applicable Beyond Grace

This pattern works for any multi-repo architecture where:
  • Repository A (protocol) is separate from Repository B (implementation)
  • Both have public-facing documentation
  • You want independent deployment cadences
  • Cross-refs must survive DNS/URL changes
Checklist for copying this pattern:
  • Identify conceptual boundary between repos (protocol vs. impl)
  • Create separate doc sites (Astro + Starlight or equivalent)
  • Establish link normalization: internal = /, cross-repo = https://
  • Gate each migration step with a passing build
  • Audit for redaction before publishing (remove budgets, secrets, personal data)
  • Verify 100% of cross-site links with curl/HEAD requests

​
Lessons for Next Time

  1. Start with redaction mapping: Before writing a single doc, list what’s sensitive. Filter as you go, not after.
  2. Build-driven gates are non-negotiable: If a docs migration step doesn’t build cleanly, don’t proceed. No “we’ll fix it later.”
  3. Absolute URLs for external cross-refs: Using relative paths for cross-workspace links creates future lock-in. Use HTTPS from the start.
  4. Sidebar is not shared: Don’t try to keep sidebars in sync across repos. Each site has its own sidebar; external links are one-way.
  5. Content audit is part of the workflow: Don’t add content audit as an afterthought. Make it a formal taskset gate.
Related: Cross-Workspace Link Strategy (companion learning documenting the specific link patterns), Taskset-Gated Documentation Workflow (companion learning documenting the six-taskset process).