feat(phase2): wiki-as-SoT parallel sync scaffold#21
Merged
Conversation
The sed range pattern '/^---$/,/^---$/p' restarts after termination, capturing every '^---$' pair in the file. Files with markdown HR separators in the body (api-reference.md upstream has 65) had their content doubled on each sync, then re-doubled on the next. Replaced with an awk single-state-machine: increments n on each ---, prints the line, exits at the second ---; in between, prints body lines. Idempotent for files with body HR separators; behavior unchanged for files without (mcp.md, platform.md, etc.). Verified by re-running the sync after the fix: Sync complete: 0 updated, 4 unchanged, 0 failed api-reference.md stays at 1861 lines (was doubling to 2906 with the sed pattern). Closes #19. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 2 of wiki-as-docs-sot-migration. Adds the parallel sync path that reads from AEGIS wiki and writes to src/content/docs/. Runs alongside legacy docs-sync.sh — does not replace it. Output uses a -from-wiki suffix so the POC pages route at /mcp-from-wiki/ for side-by-side comparison with the legacy /mcp/ rendering. - src/content/config.ts — add optional lastVerified + sourceSlug fields on the docs collection schema. Surfaces the wiki page's verification date and source slug for "Verified <date>" stamps and back-links to the AEGIS wiki source. - scripts/wiki-publish-manifest.json — new manifest schema (v4) mapping wiki slugs → Astro page metadata (section/order/color/tag). Phase 2 ships with one entry as POC: mcp-gateway-architecture. - scripts/docs-sync-from-wiki.sh — bash sync script. Reads from AEGIS HTTP API at $AEGIS_BASE/api/wiki/:slug (auth: bearer $AEGIS_TOKEN), parses wiki_read_page response, builds Astro frontmatter from wiki metadata + manifest cosmetics, hashes for idempotence, writes to src/content/docs/<page>. Dependency: the script needs a public HTTP wiki proxy on aegis-daemon (filed as Stackbilt-dev/aegis#582). Until that endpoint lands, the script will exit non-zero with a 404 from AEGIS — the POC page in src/content/docs/mcp-from-wiki.md is hand-generated for now to validate the round-trip. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Round-trip validation artifact for the wiki-as-SoT migration. Content is a verbatim copy of the AEGIS wiki page mcp-gateway-architecture (revision MToyMDI2... captured 2026-05-02 via wiki_read_page MCP tool); frontmatter built per the new docs-sync-from-wiki.sh script's pattern (manifest cosmetics + wiki lastVerified + wiki sourceSlug). Routes at /mcp-from-wiki for side-by-side comparison with the existing /mcp page (legacy gh-API sync of stackbilt-web/docs/mcp.md). Once Stackbilt-dev/aegis#582 lands the AEGIS HTTP wiki proxy, docs-sync-from-wiki.sh will regenerate this file automatically and the round-trip becomes script-driven instead of hand-generated. Astro build: 9 → 10 pages, /mcp-from-wiki/index.html added. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 2 of the wiki-as-docs-SoT migration (AEGIS wiki slug
wiki-as-docs-sot-migration). Adds a parallel sync that reads from AEGIS wiki and writes tosrc/content/docs/. Runs alongside legacydocs-sync.sh— does not replace it. Output uses a-from-wikisuffix so POC pages render at/mcp-from-wiki/for side-by-side comparison with the existing/mcp/.What's in this PR
src/content/config.tslastVerified+sourceSlugto the docs collection schema. Surfaces wiki metadata for "Verified<date>" stamps + back-links.scripts/wiki-publish-manifest.jsonmcp-gateway-architecture→mcp-from-wiki.md.scripts/docs-sync-from-wiki.sh$AEGIS_BASE/api/wiki/:slug(auth:Bearer $AEGIS_TOKEN); parses wiki_read shape; builds Astro frontmatter from wiki metadata + manifest cosmetics; hashes for idempotence; writes tosrc/content/docs/<page>.src/content/docs/mcp-from-wiki.mdmcp-gateway-architecturebody, captured 2026-05-02 viawiki_read_pageMCP tool). Validates the round-trip end-to-end.Round-trip verification
Astro build: 9 → 10 pages, new
/mcp-from-wiki/index.htmlrendered cleanly. Pre-commit hook passed on both commits.The POC page renders alongside the legacy
/mcppage (sourced fromstackbilt-web/docs/mcp.mdvia the existingdocs-sync.sh). Side-by-side after deploy:https://docs.stackbilt.dev/mcp← legacy gh-API pathhttps://docs.stackbilt.dev/mcp-from-wiki← new wiki pathSame content (the upstream
stackbilt-web/docs/mcp.mdis itself derived from the same wiki page, so they're expected to match). The comparison is the format: does the wiki round-trip produce the same rendered page that the gh-API path produces?Dependency
The script can't run end-to-end yet —
aegis.stackbilt.dev/api/wiki/:slugreturns 404 today. AEGIS only exposes wiki via MCP. FiledStackbilt-dev/aegis#582for a public HTTP wiki proxy endpoint. Once that lands,docs-sync-from-wiki.shbecomes functional and the POC file regenerates from the script instead of being hand-maintained.What's NOT in this PR (per migration plan)
mcp-gateway-architectureto replace the legacy/mcpsource) — held until script is functionalTest plan
npm run buildproduces 10 pages including/mcp-from-wiki/index.htmllastVerifiedandsourceSlugwithout validation errorshttps://docs.stackbilt.dev/mcp-from-wikiand compare againsthttps://docs.stackbilt.dev/mcp— content parity expectedStackbilt-dev/aegis#582lands: runAEGIS_TOKEN=... ./scripts/docs-sync-from-wiki.sh --dry-runand verify it reports 0 changes (idempotent) when local matches wikiMigration phase status
docs#19)2863efd3aegis#582🤖 Generated with Claude Code