@@ -1,11 +1,11 @@
 guide-path: /.well-known/assistant-guide.txt
-guide-version: 1.0.0
-guide-sha256: dd3912efc5225ba7439ab95c880102ab01789d56ef5a8d8b3882ae2e0c33675d
-guide-bytes: 7052
+guide-version: 1.0.1
+guide-sha256: 498a0038bccfcd242a318c59311d86c91da71f96e3e8e7003727f98bd569deb6
+guide-bytes: 7778
 immutable-release-url: https://github.com/snapsynapse/knowledge-as-code-template
 profile: human-verifiable-assistant-guide
 profile-version: 0.3.0
 canonical-url: https://knowledge-as-code.com/.well-known/assistant-guide.txt
 repository-url: https://github.com/snapsynapse/knowledge-as-code-template
-released-at: 2026-05-25T00:00:00Z
+released-at: 2026-06-12T00:00:00Z
 changelog-url: https://github.com/snapsynapse/knowledge-as-code-template/blob/main/CHANGELOG.md
@@ -4,13 +4,13 @@ Assistant Guide: Knowledge-as-Code template local verification
 identifier: assistant-guide
 profile: human-verifiable-assistant-guide
 profile-version: 0.3.0
-guide-version: 1.0.0
+guide-version: 1.0.1
 applies-to: knowledge-as-code-template
 canonical-url: https://knowledge-as-code.com/.well-known/assistant-guide.txt
 repository-url: https://github.com/snapsynapse/knowledge-as-code-template
 source-path: /.well-known/assistant-guide.txt
 manifest-url: https://knowledge-as-code.com/.well-known/assistant-guide-manifest.txt
-last-reviewed: 2026-05-25
+last-reviewed: 2026-06-12
 reviewed-by: PAICE.work PBC
 status: active
 recommended-verifier: https://guidecheck.org/verify
@@ -64,6 +64,19 @@ The task uses local Node.js and shell scripts already present in the repository.
 Build actions regenerate tracked static artifacts under docs/ and demo/.
 Validation actions inspect local files and do not require network access.
 
+Repository-specific constraints
+Entity filenames, mapping IDs, and mapping references must be lowercase slug
+IDs using only a-z, 0-9, and single hyphens. The filename without .md is the
+entity ID. Do not create data files with spaces, underscores, uppercase
+letters, punctuation, path separators, or unsafe URL characters in the ID.
+
+Generated-output handling
+docs/ and demo/ are generated outputs in this repository. Do not hand-edit
+generated HTML, JSON API files, sitemap, agents.json, llms.txt, RSS, or copied
+assets. Update source data, project.yml, or scripts first, then regenerate the
+outputs. The build script cleans only generator-owned paths in the selected
+output directory and refuses unsafe output directories.
+
 Actions
 
 [action]
 
@@ -13,7 +13,23 @@ pattern.
 
 ## [Unreleased]
 
+## [1.0.2] — 2026-06-12
+
+### Added
+- Added eval coverage for unsafe output directories, stale generated-output cleanup, unsafe entity IDs, status badge contrast, generated URL path stability, and JSON-RPC notification silence.
+- Documented slug-safe entity IDs, generated-output cleanup behavior, and MCP notification semantics across human docs and agent-facing guides.
+
+### Changed
+- Bumped the GuideCheck assistant guide to `1.0.1` with repository-specific generated-output and slug-ID constraints.
+- Regenerated tracked `docs/` and `demo/` outputs after status badge contrast hardening.
+
 ### Fixed
+- Refused unsafe build output directories before cleanup and removed stale files only under generator-owned output paths.
+- Rejected unsafe filenames, mapping IDs, and mapping references during validation and build.
+- Encoded generated URL path segments after strict ID validation.
+- Computed status badge foreground colors from background luminance instead of hard-coding theme text colors.
+- Stopped returning JSON-RPC errors for notifications that omit `id`.
+- Refreshed content-provenance hashes after intentional README, guide, and tooling updates.
 - Made `scripts/build.js` output reproducible by sourcing generated-output timestamps (`meta.generated`, `agents.json` `last_updated`, sitemap `lastmod`, RSS `lastBuildDate`) from the freshest date in the data rather than wall-clock time. The "generated outputs are current" CI gate could never pass before, because each rebuild stamped a new `new Date()` into committed artifacts.
 
 ## [1.0.1] — 2026-05-30
@@ -136,7 +152,8 @@ canonical pattern definition at <https://knowledge-as-code.com/>.
   site generator, `scripts/validate.js` cross-reference linter, example data for ISO 27001 and
   NIST CSF, dark/light themed static site output, JSON API, bridge pages, `CNAME` fixture.
 
-[Unreleased]: https://github.com/snapsynapse/knowledge-as-code-template/compare/v1.0.1...HEAD
+[Unreleased]: https://github.com/snapsynapse/knowledge-as-code-template/compare/v1.0.2...HEAD
+[1.0.2]: https://github.com/snapsynapse/knowledge-as-code-template/releases/tag/v1.0.2
 [1.0.1]: https://github.com/snapsynapse/knowledge-as-code-template/releases/tag/v1.0.1
 [1.0.0]: https://github.com/snapsynapse/knowledge-as-code-template/releases/tag/v1.0.0
 [0.4.0]: https://github.com/snapsynapse/knowledge-as-code-template/releases/tag/v0.4.0
 
@@ -27,8 +27,8 @@
 #   - This file itself
 
 bundle: knowledge-as-code-template
-bundle_version: 1.0.1
-bundle_date: 2026-05-30
+bundle_version: 1.0.2
+bundle_date: 2026-06-12
 description: >
   Knowledge as Code starter template — scaffolds a KaC site with
   Primary/Container/Authority/Secondary entities, gist ontology binding,
@@ -47,22 +47,22 @@ files:
 
   - path: README.md
     role: protocol
-    hash: sha256:61811994959fe4f8d52f1802593d79957527fa890f3573aeea1f3e96f0105c13
+    hash: sha256:d17355f0cb940e4d9423b5931c1035df36f675df08fe70b026aa8e82e46b5593
     note: Template overview
 
   - path: assistant-guide.txt
     role: guidecheck
-    hash: sha256:dd3912efc5225ba7439ab95c880102ab01789d56ef5a8d8b3882ae2e0c33675d
+    hash: sha256:498a0038bccfcd242a318c59311d86c91da71f96e3e8e7003727f98bd569deb6
     note: Repository-root GuideCheck assistant guide copy
 
   - path: .well-known/assistant-guide.txt
     role: guidecheck
-    hash: sha256:dd3912efc5225ba7439ab95c880102ab01789d56ef5a8d8b3882ae2e0c33675d
+    hash: sha256:498a0038bccfcd242a318c59311d86c91da71f96e3e8e7003727f98bd569deb6
     note: Canonical GuideCheck assistant guide
 
   - path: .well-known/assistant-guide-manifest.txt
     role: guidecheck
-    hash: sha256:6ab8b1b2b9f72be25be2de00c2081cc7d5250531adb859db410b92645f5c8d82
+    hash: sha256:f9294ffd17a69a09116d4dcb3638b1c7d652952960b624ba3d98eacb973218c8
     note: GuideCheck sidecar manifest
 
   - path: project.yml
@@ -72,12 +72,12 @@ files:
 
   - path: scripts/build.js
     role: tooling
-    hash: sha256:eaf0e8aed6fc03f43ac3ead2df3acfa7ac7b392bbd055a11e63540e9fe9cf017
+    hash: sha256:bcbdbb8d093fc9fe48e0b09f44c7097e333477e92d3c1193bd4606820cdfa83d
     note: Static site generator
 
   - path: scripts/validate.js
     role: tooling
-    hash: sha256:d1da14cd8659bbfeaa6b6402464597b200c40c656be72cb3b2c6ffe5edebf284
+    hash: sha256:f7fba6ac85c40a0a46516739128154f754e3f83d25a8e5b79ef6625ff43ae6fc
     note: Cross-reference validator
 
   - path: scripts/verify.js
 
@@ -10,9 +10,13 @@ This guide captures the exact prep work, in the order it has to happen.
 
 - Your fork has its own canonical `project.yml`, real data under `data/`, and a
   working build (`node scripts/build.js` succeeds).
+- Entity filenames, mapping IDs, and mapping references are lowercase slug IDs
+  using only `a-z`, `0-9`, and single hyphens. Run `node scripts/validate.js`
+  before publishing so unsafe IDs are rejected before they become MCP-visible
+  data.
 - `node mcp-server.js` works locally — pipe `{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}`
   into it and you should get back your tools.
-- An npm account ([npmjs.com](https://www.npmjs.com/signup)) with 2FA enabled.
+- An npm account ([npmjs.com](https://npmjs.com/signup)) with 2FA enabled.
 - A GitHub account that matches the org/user owning the repo.
 
 ## Step 1 — choose a package name
@@ -100,6 +104,10 @@ echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node mcp-ser
 
 You should get back your tools.
 
+The server follows JSON-RPC notification semantics. Messages without an `id`
+are notifications and do not receive responses, including unknown-method
+notifications.
+
 ## Step 4 — publish to npm
 
 Authenticate (a one-time setup; uses your browser):
@@ -186,7 +194,7 @@ After any data update or server change:
 **npm:** if you use a "Publish" classic token, every publish requires a 2FA
 browser flow. If you use an "Automation" token, it bypasses 2FA — easier for
 recurring publishes. Create one at
-[npmjs.com/settings/~/tokens](https://www.npmjs.com/settings/~/tokens).
+[npmjs.com/settings/~/tokens](https://npmjs.com/settings/~/tokens).
 
 **mcp-publisher:** the registry uses short-lived JWTs. If your session has
 been idle for an hour or so, the next `mcp-publisher publish` will fail with
 
@@ -31,7 +31,7 @@ Built examples using this template:
 1. **Use this template** -- on GitHub, click the green "Use this template" button (not "Clone"). This creates a new repo with no git history and no upstream connection. Cloning is fine for local exploration but won't give you a clean starting repo.
 2. **Edit `project.yml`** -- start with the entity names (`entities.primary.name`, `entities.container.name`, etc.) and groups. You can adjust colors and navigation later. Leave `url` until your GitHub repo is configured.
 3. **Replace example data** -- delete the files in `data/examples/requirements/`, `data/examples/frameworks/`, `data/examples/organizations/`, and `data/examples/mapping/index.yml`, then add your own. See [Replacing example data](#replacing-example-data) and [`data/_schema.md`](data/_schema.md) for the format.
-4. **Build** -- `node scripts/build.js`. A successful build prints `Build complete — N HTML pages, N JSON API files`. Check the `docs/` directory for the output, and open any HTML file in a browser to verify it looks right.
+4. **Build** -- `node scripts/build.js`. A successful build prints `Build complete — N HTML pages, N JSON API files`. Check the `docs/` directory for the output, and open any HTML file in a browser to verify it looks right. The build cleans generator-owned paths in the output directory before writing fresh files, so removed or renamed entities do not leave stale generated pages behind.
 5. **Deploy** -- choose your Pages strategy. This repo validates builds in CI, but it does not auto-deploy template forks by default. If you want automated deployment, add a Pages publish step for your repo.
 6. **(Optional) Publish your knowledge base as an MCP server** -- if you want anyone to install your knowledge base as an MCP-aware agent tool via `npx -y your-package`, follow [PUBLISH-MCP.md](PUBLISH-MCP.md). It walks through the package.json prep, npm publish, and Official MCP Registry submission, with the gotchas that bit us when we did this for three sibling projects.
 
@@ -42,6 +42,7 @@ This repository intentionally tracks generated output in both `docs/` and `demo/
 - `docs/` is the template-default generated site output.
 - `demo/` is the canonical reference build used for `https://knowledge-as-code.com/demo/`.
 - Neither directory should be edited by hand. Regenerate them with `node scripts/build.js` or the `KAC_OUTPUT_DIR=demo KAC_SITE_URL="https://knowledge-as-code.com/demo/" node scripts/build.js` variant.
+- During each build, the generator removes only paths it owns in the target output directory (`api/`, `assets/`, entity/bridge page directories, and generated root files). It refuses to clean the repository root or a parent directory.
 
 Template forks do not need to follow this policy. A fork can either:
 
@@ -151,6 +152,8 @@ All domain-specific settings live in `project.yml`:
 
 Generated pages normalize external URLs to `https` and bare domains. Avoid `http`, `javascript:`, and `www` in project data; unsafe protocols are dropped from generated links. Configured colors should be hex values such as `#4fc3f7`; invalid color values fall back to safe defaults.
 
+Entity filenames and mapping IDs must be lowercase slug IDs: `a-z`, `0-9`, and single hyphens only, such as `access-control` or `iso-27001`. The filename without `.md` is the entity ID. Mapping references must use those same IDs. `node scripts/validate.js` and `node scripts/build.js` both reject unsafe IDs before generated HTML, filesystem paths, JSON discovery files, or MCP responses are produced.
+
 ## Replacing example data
 
 The template ships with example data in `data/examples/` (ISO 27001, NIST CSF). To replace it with your own domain:
@@ -177,7 +180,7 @@ npm run eval
 
 That runs the broader smoke/eval suite covering builds, links, API shape, parser fixtures, MCP smoke, and documentation consistency.
 
-The build script looks for data in `data/examples/` first, then `data/`. You can rename `data/examples/` to `data/` if you prefer a flatter structure.
+The build script looks for data in `data/examples/` first, then `data/`. You can rename `data/examples/` to `data/` if you prefer a flatter structure. Keep filenames slug-safe because the generated site, JSON API, MCP tools, search index, sitemap, and agents.json all use the filename-derived IDs.
 
 **What to keep:** Only `data/` contents and `project.yml` values need replacing. Do not delete `scripts/`, `.github/workflows/`, `mcp-server.js`, `mcp.json`, or `package.json` — these are the template engine and deployment config.
 
 
@@ -4,13 +4,13 @@ Assistant Guide: Knowledge-as-Code template local verification
 identifier: assistant-guide
 profile: human-verifiable-assistant-guide
 profile-version: 0.3.0
-guide-version: 1.0.0
+guide-version: 1.0.1
 applies-to: knowledge-as-code-template
 canonical-url: https://knowledge-as-code.com/.well-known/assistant-guide.txt
 repository-url: https://github.com/snapsynapse/knowledge-as-code-template
 source-path: /.well-known/assistant-guide.txt
 manifest-url: https://knowledge-as-code.com/.well-known/assistant-guide-manifest.txt
-last-reviewed: 2026-05-25
+last-reviewed: 2026-06-12
 reviewed-by: PAICE.work PBC
 status: active
 recommended-verifier: https://guidecheck.org/verify
@@ -64,6 +64,19 @@ The task uses local Node.js and shell scripts already present in the repository.
 Build actions regenerate tracked static artifacts under docs/ and demo/.
 Validation actions inspect local files and do not require network access.
 
+Repository-specific constraints
+Entity filenames, mapping IDs, and mapping references must be lowercase slug
+IDs using only a-z, 0-9, and single hyphens. The filename without .md is the
+entity ID. Do not create data files with spaces, underscores, uppercase
+letters, punctuation, path separators, or unsafe URL characters in the ID.
+
+Generated-output handling
+docs/ and demo/ are generated outputs in this repository. Do not hand-edit
+generated HTML, JSON API files, sitemap, agents.json, llms.txt, RSS, or copied
+assets. Update source data, project.yml, or scripts first, then regenerate the
+outputs. The build script cleans only generator-owned paths in the selected
+output directory and refuses unsafe output directories.
+
 Actions
 
 [action]
 
@@ -8,6 +8,9 @@ This file documents the file format for each entity type. All data files use YAM
 
 **Example:** `requirements/access-control.md`
 
+The filename without `.md` is the entity ID. It must be a lowercase slug using
+only `a-z`, `0-9`, and single hyphens, such as `access-control`.
+
 ```yaml
 ---
 id: access-control              # Required. Kebab-case identifier, must match filename
@@ -43,6 +46,9 @@ One paragraph describing the requirement.
 
 **Example:** `frameworks/iso-27001.md`
 
+The filename without `.md` is the container ID. It must be a lowercase slug
+using only `a-z`, `0-9`, and single hyphens, such as `iso-27001`.
+
 ```yaml
 ---
 name: ISO 27001                   # Required. Human-readable name
@@ -120,6 +126,9 @@ last_verified: 2026-03-25        # Optional. Date of last verification check
 
 **Example:** `organizations/iso.md`
 
+The filename without `.md` is the authority ID. It must be a lowercase slug
+using only `a-z`, `0-9`, and single hyphens, such as `iso`.
+
 ```yaml
 ---
 id: iso                                           # Required. Kebab-case identifier
@@ -145,7 +154,7 @@ The heading name should match your container entity's plural name (e.g., "Regula
 
 **Path:** `data/examples/mapping/index.yml` (configured in `project.yml` as `mapping.file`)
 
-The mapping file connects containers to primaries through secondary (provision) entities:
+The mapping file connects containers to primaries through secondary (provision) entities. Mapping IDs and every entity reference must use the same lowercase slug format as filenames.
 
 ```yaml
 - id: iso-27001-access-control        # Required. Unique provision ID (kebab-case)
@@ -163,9 +172,11 @@ The `regulation` field should use your container entity name from config (the fi
 
 ## File naming
 
-- All files use kebab-case: `access-control.md`, `iso-27001.md`
-- The filename (without `.md`) is used as the entity ID for primaries and authorities
-- Container files use the `name` frontmatter field (lowercased, spaces replaced with hyphens) as their ID
+- All files use lowercase slug filenames: `access-control.md`, `iso-27001.md`
+- Slugs may contain only `a-z`, `0-9`, and single hyphens
+- The filename without `.md` is used as the entity ID for primaries, containers, and authorities
+- Mapping IDs and mapping references must use the same slug format
+- `node scripts/validate.js` and `node scripts/build.js` reject unsafe IDs
 
 ## URL and style safety
 
@@ -175,6 +186,7 @@ The `regulation` field should use your container entity name from config (the fi
 - Group, status, and theme colors in `project.yml` should be hex colors. Invalid values fall back to safe defaults.
 - Group and status names are normalized before use as CSS class names.
 - Generated comparison-page labels are escaped before client-side insertion.
+- Generated URL path segments are derived only from validated entity IDs.
 
 ## Adding new entities
 
 
@@ -22,7 +22,7 @@
 .status-badge.active { background: #4caf50; color: #000; }
 :is(html, body).light-mode .status-badge.active { background: #1b7d1b; color: #fff; }
 .status-badge.draft { background: #ff9800; color: #000; }
-:is(html, body).light-mode .status-badge.draft { background: #e65100; color: #fff; }
+:is(html, body).light-mode .status-badge.draft { background: #e65100; color: #000; }
 .status-badge.deprecated { background: #607d8b; color: #000; }
 :is(html, body).light-mode .status-badge.deprecated { background: #455a64; color: #fff; }
 :root { --accent: #4fc3f7; }
 
@@ -23,7 +23,7 @@
 .status-badge.active { background: #4caf50; color: #000; }
 :is(html, body).light-mode .status-badge.active { background: #1b7d1b; color: #fff; }
 .status-badge.draft { background: #ff9800; color: #000; }
-:is(html, body).light-mode .status-badge.draft { background: #e65100; color: #fff; }
+:is(html, body).light-mode .status-badge.draft { background: #e65100; color: #000; }
 .status-badge.deprecated { background: #607d8b; color: #000; }
 :is(html, body).light-mode .status-badge.deprecated { background: #455a64; color: #fff; }
 :root { --accent: #4fc3f7; }