From 6eabad4e2cf7a4f4b836cde53ccbadd4a284ab2a Mon Sep 17 00:00:00 2001 From: Nathan Schram <5553883+nathanschram@users.noreply.github.com> Date: Wed, 6 May 2026 07:16:09 +0000 Subject: [PATCH] docs: protect synced FAQ path in AGENTS.md and CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds an explicit "Synced Documentation Paths" section to AGENTS.md (canonical) and a Key Files row in CLAUDE.md so future sessions know: - docs/faq/index.md is consumed by the marketing-site sync pipeline (scripts/docs-sync.config.ts under contextdocs). The upstream build hard-fails if the directory goes missing. - Update the FAQ only when an answer goes stale — not on every release. - Existing constraints (each H2 ends with ?, no placeholders, Australian English, banned-phrase rules from doc-standards.md) carry over to every revision. Follow-up to #25 / #26 — keeps the FAQ from being deleted by routine cleanup sweeps and makes the maintenance contract explicit. Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 6 ++++++ CLAUDE.md | 1 + 2 files changed, 7 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 9460ae1..d27da95 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,3 +51,9 @@ Invoke as `/contextdocs:command-name` in Claude Code, or as prompts in Codex CLI - `content-filter-guard.sh` — Write guard for high-risk OSS files - `context-guard-stop.sh` — session-end context doc nudge (Tier 1) - `context-commit-guard.sh` — pre-commit context doc enforcement (Tier 2) + +## Synced Documentation Paths + +These paths are consumed by external sync pipelines. Treat as protected — the upstream build fails if they go missing. + +- `docs/faq/index.md` — FAQ scaffold for the help-centre FAQPage schema (issue #25). Synced to `littlebearapps.com/help/contextdocs/faq/` by the marketing-site `scripts/docs-sync.config.ts` mapping under `contextdocs`. **Do not delete or move.** **Update only when** an answer goes stale (new install path, retired feature, top support driver becomes a new question) — not on every release. Keep the question set lean: each H2 must end with `?`, every answer must be complete (no placeholders), and Australian English / banned-phrase rules from `.claude/rules/doc-standards.md` apply. diff --git a/CLAUDE.md b/CLAUDE.md index 44f9aff..10d820f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -45,6 +45,7 @@ Pure Markdown Claude Code plugin — no JavaScript, no Python, no build step, no | `.claude/agents/docs-freshness.md` | Read-only agent — checks documentation freshness, suggests PitchDocs commands *(PitchDocs)* | | `.claude/rules/doc-standards.md` | Auto-loaded quality rule — 4-Question Test, Lobby Principle, banned phrases *(PitchDocs)* | | `.claude/rules/docs-awareness.md` | Auto-loaded trigger map — suggests PitchDocs commands when docs-relevant work is detected *(PitchDocs)* | +| `docs/faq/index.md` | Synced FAQ — emits Schema.org `FAQPage` JSON-LD on `littlebearapps.com/help/contextdocs/faq/` via the marketing-site sync (issue #25). **Do not delete or move** — upstream build hard-fails. **Update only when** an answer goes stale, not on every release | ## Known Limitations