From 4903be18b52f222061ff62656aacd85204b74135 Mon Sep 17 00:00:00 2001 From: hfxia Date: Wed, 12 Aug 2026 22:42:17 -0400 Subject: [PATCH] fix: move authoring policy out of the docs tree docs/agent/ held internal authoring policy, but anything under docs/ is a documentation route. doom rendered those five files as /agent/* pages and SSG crashed on them, which is why doc-pr-build-valkey failed on every PR regardless of its content. The failure was invisible locally because doom.config.yml marked agent/**/* as internalRoutes and the build script passed --ignore=true. CI does not pass that flag: build-docs runs `yarn build-online-io`, which renders internal routes. CI also discards the pinned doom version -- install-dependencies runs `yarn remove @alauda/doom && yarn add @alauda/doom` -- so it builds with the latest doom, which adds a generated /agent/products page in the same namespace. That page is the one named in the pipeline log. Moves the files to a root-level agent/ directory, matching redis-docs, which keeps its agent instructions and TERMINOLOGY_CANDIDATES.md at the repository root and has never had a docs/agent/ directory. With the files out of the docs tree, internalRoutes and --ignore=true have nothing left to hide, so both are removed. Keeping them would restore the local/CI divergence that masked this. Verified against doom 2.5.4, the version CI installs: the build fails on /agent/* before this change and completes with zero errors after. Also green on the pinned 1.12.1, and dist/agent/ is no longer produced. --- AGENTS.md | 11 +++++++---- {docs/agent => agent}/ARCHITECTURE_FACTS.md | 0 {docs/agent => agent}/CONTENT_AUDIT.md | 0 {docs/agent => agent}/SOURCE_POLICY.md | 0 {docs/agent => agent}/TECHNICAL_WRITING_POLICY.md | 0 {docs/agent => agent}/TERMINOLOGY.md | 0 doom.config.yml | 2 -- llmstxt-config.yaml | 2 +- package.json | 4 ++-- 9 files changed, 10 insertions(+), 9 deletions(-) rename {docs/agent => agent}/ARCHITECTURE_FACTS.md (100%) rename {docs/agent => agent}/CONTENT_AUDIT.md (100%) rename {docs/agent => agent}/SOURCE_POLICY.md (100%) rename {docs/agent => agent}/TECHNICAL_WRITING_POLICY.md (100%) rename {docs/agent => agent}/TERMINOLOGY.md (100%) diff --git a/AGENTS.md b/AGENTS.md index 7621590..74b82f5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,10 +2,13 @@ Before writing or changing technical documentation, read: -- `docs/agent/TECHNICAL_WRITING_POLICY.md` -- `docs/agent/TERMINOLOGY.md` -- `docs/agent/ARCHITECTURE_FACTS.md` -- `docs/agent/SOURCE_POLICY.md` +- `agent/TECHNICAL_WRITING_POLICY.md` +- `agent/TERMINOLOGY.md` +- `agent/ARCHITECTURE_FACTS.md` +- `agent/SOURCE_POLICY.md` + +These live at the repository root, outside `docs/`. Anything under `docs/` is +rendered as a documentation route and published; authoring policy must not be. Treat `TERMINOLOGY.md` as the canonical vocabulary. Verify product claims against the current `valkey-operator` `origin/master` source, generated CRDs, and packaged diff --git a/docs/agent/ARCHITECTURE_FACTS.md b/agent/ARCHITECTURE_FACTS.md similarity index 100% rename from docs/agent/ARCHITECTURE_FACTS.md rename to agent/ARCHITECTURE_FACTS.md diff --git a/docs/agent/CONTENT_AUDIT.md b/agent/CONTENT_AUDIT.md similarity index 100% rename from docs/agent/CONTENT_AUDIT.md rename to agent/CONTENT_AUDIT.md diff --git a/docs/agent/SOURCE_POLICY.md b/agent/SOURCE_POLICY.md similarity index 100% rename from docs/agent/SOURCE_POLICY.md rename to agent/SOURCE_POLICY.md diff --git a/docs/agent/TECHNICAL_WRITING_POLICY.md b/agent/TECHNICAL_WRITING_POLICY.md similarity index 100% rename from docs/agent/TECHNICAL_WRITING_POLICY.md rename to agent/TECHNICAL_WRITING_POLICY.md diff --git a/docs/agent/TERMINOLOGY.md b/agent/TERMINOLOGY.md similarity index 100% rename from docs/agent/TERMINOLOGY.md rename to agent/TERMINOLOGY.md diff --git a/doom.config.yml b/doom.config.yml index fd4e798..e0c87e0 100644 --- a/doom.config.yml +++ b/doom.config.yml @@ -4,5 +4,3 @@ lang: en api: crds: - docs/shared/crds/*.yaml -internalRoutes: - - agent/**/* diff --git a/llmstxt-config.yaml b/llmstxt-config.yaml index 342dc72..1ddbe5c 100644 --- a/llmstxt-config.yaml +++ b/llmstxt-config.yaml @@ -18,7 +18,7 @@ exclude_patterns: - "README.md" - "**/.DS_Store" # Authoring policy for agents, not product documentation. - - "docs/agent/**" + - "agent/**" - "AGENTS.md" - "CLAUDE.md" grouping_base_path: "docs/en" diff --git a/package.json b/package.json index 20d2e06..21491da 100644 --- a/package.json +++ b/package.json @@ -5,9 +5,9 @@ }, "scripts": { "dev": "doom dev", - "build": "doom --ignore=true build", + "build": "doom build", "lint": "doom lint", - "serve": "doom --ignore=true serve", + "serve": "doom serve", "translate": "doom translate" }, "packageManager": "yarn@4.9.4"