davidahmann · davidahmann · Aug 11, 2026 · Aug 11, 2026 · Aug 11, 2026
@@ -1,8 +1,8 @@
 blank_issues_enabled: false
 contact_links:
   - name: Architecture discussion
-    url: https://github.com/davidahmann/production-agent-engineering/discussions
+    url: https://github.com/davidahmann/fde-guide/discussions
     about: Ask design and implementation questions in Discussions.
   - name: Security report
-    url: https://github.com/davidahmann/production-agent-engineering/security/advisories/new
+    url: https://github.com/davidahmann/fde-guide/security/advisories/new
     about: Report vulnerabilities privately.
@@ -0,0 +1,55 @@
+name: Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build site
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+      - name: Build and test site
+        run: npm run test:site
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site-dist
+
+  deploy:
+    name: Deploy site
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
@@ -1,4 +1,8 @@
 node_modules/
 coverage/
+site-dist/
+.env
+.env.*
+!.env.example
 .DS_Store
 *.log
@@ -38,6 +38,7 @@ Do not load the entire repository by default. Use one skill or task route, then
 | [`library/`](library/00-start-here.md) | Explains design decisions, implementation sequence, and failure modes | Human-readable guidance |
 | [`operations/`](operations/README.md) | Defines release, telemetry, service objectives, incident response, and change | Operating contract |
 | [`research/`](research/README.md) | Records dated sources, portable findings, and caveats | Evidence for claims that can change |
+| [`site/`](site/site.config.mjs) | Maps canonical Markdown into the public web guide and provides its minimal UI | Generated discovery layer; never a second content source |
 | [`docs/maintainers/`](docs/maintainers/repository-maintenance.md) | Defines repository stewardship and release maintenance | Internal maintainer runbook |
 | [`.agents/skills/`](.agents/skills/) | Provides focused FDE and AI-engineering workflows | Optional task interfaces over canonical repository artifacts; not authority or runtime capabilities |
 | [`scripts/`](scripts/validate-repository.mjs) | Validates repository-wide structure and cross-references | Automated repository guardrail |
@@ -83,7 +84,7 @@ Repository-local skills are instruction-only workflows. They grant no tool acces
 | Run a service review | [Production service review](templates/production-service-review.md) → [SLO scorecard](operations/slo-scorecard.md) → [behavior monitoring](operations/behavior-monitoring.md) → [change management](operations/change-management.md) | Outcome, adoption, reliability, safety, cost, change, ownership, and retirement decisions |
 | Update changing guidance | [Research policy](research/README.md) → dated primary source → affected pattern, control, or library page | Attributed claim, caveat, review date, and linked implementation impact |
 | Change operations or a runbook | Relevant OPS controls → trace and effect contracts → affected operations document → example and recovery tests | Consistent telemetry, SLO, detection, containment, recovery, and release behavior |
-| Change repository, CI, or community metadata | [README](README.md) → [concise Guide](guide/README.md) when public method or hierarchy changes → package metadata, citation, and changelog → workflow or community file → validator | Consistent public metadata, safe automation, navigation, and validation |
+| Change repository, site, CI, or community metadata | [README](README.md) → [concise Guide](guide/README.md) when public method or hierarchy changes → [`site/site.config.mjs`](site/site.config.mjs) and site tests when web discovery changes → package metadata, citation, and changelog → workflow or community file → validator | Consistent public metadata, safe automation, navigation, generated site, and validation |
 | Add or change a repository skill | Target [`SKILL.md`](.agents/skills/) → directly linked controls and artifacts → `agents/openai.yaml` → skill and repository tests → public navigation | Focused trigger, bounded workflow, clear output, no duplicate methodology, catalog registration, and validated metadata |
 
 ## Artifact sequence for a new system
@@ -129,6 +130,7 @@ If these disagree, do not silently choose one. Identify the conflict, preserve t
 - New solution artifacts compose existing controls, blueprints, templates, and examples around one recurring business flow, industry specialization, or horizontal delivery boundary. They state maturity, smallest useful slice, acceptance and operating contracts, customer-specific work, and what they do not prove.
 - New examples include a design record, decision-mechanism rationale, domain model, tool contracts where applicable, eval cases, threat model, and executable verification when feasible.
 - Recommendations based on changing platform behavior cite a dated primary source in `research/`.
+- The public site projects canonical repository Markdown through `site/site.config.mjs`; do not copy or fork guide prose into a separate site corpus.
 - Vendor metrics remain attributed; experimental patterns remain labeled.
 - Every new reusable canonical artifact is added to `catalog.json` with a stable ID and repository-contained path. Community files and explanatory library pages remain uncataloged unless explicitly designated.
 - Repository skills remain thin interfaces over canonical artifacts: frontmatter contains only `name` and `description`, trigger scopes do not overlap materially, UI metadata names the skill explicitly, and no skill claims tool or approval authority.
@@ -156,7 +158,7 @@ If these disagree, do not silently choose one. Identify the conflict, preserve t
 3. Inspect the governing control, schema, blueprint, example, and evidence before editing.
 4. Make the smallest coherent change and update coupled artifacts where a contract changes.
 5. Add regression coverage for a fix and positive plus negative tests for a safety-contract change.
-6. Run targeted tests, then the full validation gate.
+6. Run targeted tests, including `npm run test:site` for public web changes, then the full validation gate.
 7. Review the diff for unsupported claims, stale links, secrets, private data, machine-local paths, placeholders, and accidental scope expansion.
 8. Report changed artifacts, verification performed, remaining risks, and any migration or rollback requirement.
 9. Do not commit, push, tag, release, or change GitHub settings unless the user explicitly authorizes it.
@@ -174,7 +176,7 @@ npm test
 git diff --check
 ```
 
-For a focused iteration, use `npm run test:markdown`, `npm run test:paths`, `npm run test:repository`, `npm run test:contracts`, `npm run test:tool-security`, `npm run test:telemetry`, `npm run test:governance`, `npm run test:release-integrity`, `npm run test:release-gates`, `npm run test:solutions`, `npm run test:value-framework`, `npm run test:skills`, `npm run test:policy`, `npm run test:reference`, or `npm run test:evals`; run the full gate before declaring the repository change complete.
+For a focused iteration, use `npm run test:markdown`, `npm run test:paths`, `npm run test:repository`, `npm run test:contracts`, `npm run test:tool-security`, `npm run test:telemetry`, `npm run test:governance`, `npm run test:release-integrity`, `npm run test:release-gates`, `npm run test:solutions`, `npm run test:value-framework`, `npm run test:skills`, `npm run test:policy`, `npm run test:reference`, `npm run test:evals`, `npm run test:hybrid`, or `npm run test:site`; run the full gate before declaring the repository change complete.
 
 A change is complete only when:
 

@@ -4,6 +4,10 @@ Notable changes to this project are recorded here.
 
 ## [Unreleased]
 
+- Add a generated GitHub Pages guide with focused reader routes, accessible navigation, local search, canonical and social metadata, structured data, sitemap, crawler policy, and a machine-readable web index without creating a second content corpus.
+- Add a human-readable production AI security and action-boundary chapter that routes identity, data access, tools, capabilities, egress, approvals, effects, readback, tests, and operations into one implementation sequence.
+- Add deterministic site build and regression tests, SHA-pinned Pages deployment, corrected community links, and public navigation for the web guide.
+
 ## [1.11.0] - 2026-08-10
 
 - Add an owned field-contribution path that classifies customer configuration, target-owned extensions, shared product/platform work, time-bounded experiments, and prohibited or deferred work before implementation.

@@ -33,6 +33,7 @@ Pull requests must keep the repository validator green and include regression co
 - Changeable platform claims cite a dated primary source in `research/`.
 - Vendor metrics remain attributed; experimental findings remain labeled.
 - Model output never authorizes effects, exposes secrets, changes its evaluator, or proves task completion.
+- Public site pages are generated from canonical Markdown through `site/site.config.mjs`; improve the source guide instead of creating duplicate web-only prose.
 
 ## Evidence changes
 

@@ -4,13 +4,13 @@
 
 ![The FDE Guide: Discover value, design the system, govern decisions, release safely, operate outcomes](assets/fde-guide-banner.svg)
 
-An independent, open-source guide and engineering kit for turning a real customer or internal workflow into a measurable, operated AI-enabled service.
+An independent, open-source guide and engineering kit for forward deployed engineers (FDEs), internal applied-AI teams, and operators turning a real workflow into a measurable, operated AI-enabled service.
 
 [![Repository validation](https://github.com/davidahmann/fde-guide/actions/workflows/validate.yml/badge.svg)](https://github.com/davidahmann/fde-guide/actions/workflows/validate.yml)
 [![Latest release](https://img.shields.io/github/v/release/davidahmann/fde-guide)](https://github.com/davidahmann/fde-guide/releases/latest)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-[Read the Guide](guide/README.md) · [Use the Handbook](playbooks/README.md) · [Run the code](#see-it-working) · [Browse solutions](solutions/README.md) · [Use with an agent](#optional-use-it-with-a-coding-agent)
+[Read on the web](https://davidahmann.github.io/fde-guide/) · [Read the concise Guide](guide/README.md) · [Use the Handbook](playbooks/README.md) · [Run the code](#see-it-working) · [Browse solutions](solutions/README.md) · [Use with an agent](#optional-use-it-with-a-coding-agent)
 
 ## Choose your depth
 
@@ -63,7 +63,7 @@ The examples are in-memory teaching systems, not deployable products. Their test
 | Business value or use-case selection | [Concise Guide](guide/README.md) → [Discovery and Value](playbooks/01-discovery-and-value.md) | Bounded workflow, baseline, accepted outcome, verifier, value case, guardrails, and decision |
 | FDE or internal applied-AI delivery | [Handbook](playbooks/README.md) → current lifecycle stage | Evidence-backed path from observation through adoption, handoff, operation, and field learning |
 | AI engineering or software architecture | [Intelligence selection](library/12-software-architecture-and-intelligence-selection.md) → [blueprints](blueprints/README.md) | Smallest sufficient mechanism, coherent system boundary, contracts, failure behavior, and test plan |
-| Platform, security, release, or reliability | [Controls](controls/control-catalog.json) → [release gates](operations/release-gates.md) → [operations](operations/README.md) | Explicit authority, compatible release, telemetry, recovery, change, and retirement evidence |
+| Platform, security, release, or reliability | [Security and action boundaries](library/15-production-ai-security-and-action-boundaries.md) → [controls](controls/control-catalog.json) → [release gates](operations/release-gates.md) → [operations](operations/README.md) | Explicit authority, compatible release, telemetry, recovery, change, and retirement evidence |
 | Technical enablement or review | [Worked systems](#see-it-working) → [templates](templates/README.md) | A concrete view of the code, design packet, evaluation, and operating evidence |
 
 ## From idea to production

@@ -19,6 +19,7 @@ This document keeps the guide coherent as research, controls, templates, example
 | `examples/` | Executable teaching evidence | Keep claims limited to tested behavior; add regressions for fixes |
 | `operations/` | Release and service contracts | Update alerts, runbooks, gates, rollback, and review cadence together |
 | `library/` | Explanatory synthesis | Cite stable source IDs and avoid duplicating normative contracts |
+| `site/` | Generated public discovery layer | Map one canonical source to one intent-led route; keep UI, metadata, crawler files, and search deterministic and free of duplicate prose |
 
 ## Claim workflow
 
@@ -50,7 +51,7 @@ This document keeps the guide coherent as research, controls, templates, example
 | Operations contract | SLO, alert, runbook, incident query, game day, example telemetry |
 | Repository skill | Trigger neighbors, value-framework and selected-solution routing, linked controls and artifacts, `agents/openai.yaml`, catalog entry, skill tests, README, AGENTS, and llms |
 | Solution artifact | Layer and coverage map, primary operating or technical boundary, referenced controls and templates, acceptance cases, operating measures, customer-specific decisions, catalog entry, navigation, and solution tests |
-| Public navigation | README hierarchy, concise Guide, AGENTS, llms, catalog, contribution docs, executable examples |
+| Public navigation or site | README hierarchy, concise Guide, AGENTS, llms, site route and metadata map, crawler files, Pages workflow, contribution docs, executable examples, and site tests |
 
 ## Research refresh
 
@@ -62,14 +63,23 @@ This document keeps the guide coherent as research, controls, templates, example
 ## Release procedure
 
 1. Inspect branch, remotes, status, and full diff.
-2. Run `npm ci --ignore-scripts`, `npm test`, and `git diff --check`; `npm test` includes solution, value-framework, skill-metadata, and catalog checks.
+2. Run `npm ci --ignore-scripts`, `npm test`, and `git diff --check`; `npm test` includes solution, value-framework, skill-metadata, site-build, link, metadata, and catalog checks.
 3. Run spelling, action workflow, dependency, and secret scans used by the current project.
 4. Confirm all new governed artifacts are cataloged and every new source ID resolves.
-5. Proofread README, concise Guide, AGENTS, llms, playbook routes, changelog, package/citation versions, and release links.
+5. Proofread README, concise Guide, AGENTS, llms, generated site routes and descriptions, playbook routes, changelog, package/citation versions, and release links.
 6. When skill discovery or packaging changes, verify `npx skills add davidahmann/fde-guide --list` from a disposable environment; do not add this network-dependent smoke test to the deterministic CI gate.
 7. Use a scoped commit and draft pull request; do not bypass protected `main`.
 8. Require CI and review before merge; tag only after the release tree and metadata agree.
 
+## Public site procedure
+
+- Treat repository Markdown as the only content source. Add a route in `site/site.config.mjs` only when the source answers a distinct reader question.
+- Keep page titles and descriptions specific, factual, and unique. Do not add keyword lists, synthetic FAQs, duplicate articles, or claims about search ranking.
+- Run `npm run test:site`, then inspect representative desktop and mobile renders before publishing a UI or navigation change.
+- The Pages workflow builds `site-dist/` in CI and deploys only that artifact. Do not commit generated output.
+- Keep `robots.txt`, `sitemap.xml`, structured metadata, the generated web `llms.txt`, and visible source links bound to the same route map.
+- After deployment, verify the canonical URL, core assets, sitemap, crawler policy, and a deep route over HTTPS. Use Search Console or equivalent measurement after ownership is configured; do not infer ranking from a successful deployment.
+
 ## Maintainer acceptance questions
 
 - Does the change improve a real user path or contract rather than add parallel prose?

@@ -3,13 +3,13 @@
   "schema_version": "1.0.0",
   "report_id": "invoice_exception_reference_report",
   "report_version": "2.0.0",
-  "summary_digest": "sha256:3e3305cc4c04a75182f7b3bddb5cf8edf46528b0ca4df6ffa623bf0b5750fa50",
+  "summary_digest": "sha256:9176f5ef8eb08c8cfcc64f207902e52a4bf9f4c2634ecaf5dd0035eb910833af",
   "suite_digest": "sha256:3d3cad18e40ae9f98741f800cede9e93b13cb13117d19234eec0ebf8f7b2799a",
   "fixture_digest": "sha256:509b32873c57164200f0e9762d907812871b2c4835bef4395eda147c3f5aca73",
   "system_digest": "sha256:75184a3ff435b73268bc23a3ff9b9189f5cefbe7854228669c60951bfaa3cc9d",
   "grader_digest": "sha256:29b30502ae2bed7f2575745f2804cdeb9e9521b2d5ebd7d7f6b98b2ffe0d9638",
   "runner_digest": "sha256:95f3962e17efc8cc792001bcc2facea613c705e45217bcaf6c0c2ebe7ab80ea2",
-  "environment_digest": "sha256:4e982ffd2905afadd71c21ab72a0d153ffaff24a7f726ecb1ccbcf29ab324cfd",
+  "environment_digest": "sha256:3e87402a84161471c1f8dc3d8b056f5831a309236751319831eb4ecb74b2a03b",
   "runner_output_digest": "sha256:a57d66d7821aeb347ec8aa90d3980a7cdcd491e8ace20d028ac3ea289da3827a",
   "runner_output": {
     "status": "passed",

@@ -111,7 +111,7 @@
           "uri": "../../package-lock.json",
           "version": "1.11.0",
           "schema_version": null,
-          "digest": "sha256:8832fa71f78069d61922dd2b25783946c2ea35acf39ad2da908eaae1f9a3886a"
+          "digest": "sha256:feac7dfe4c467c542decd9683e6835b67bb14c22f9295025f4d3f4906503d6a8"
         },
         {
           "component_id": "invoice-ontology",
@@ -233,7 +233,7 @@
           "digest": "sha256:6be09a856d1e40d69cf21a3147b686df866c474a4241ed3b24405347cd03eb97"
         }
       ],
-      "environment_digest": "sha256:4e982ffd2905afadd71c21ab72a0d153ffaff24a7f726ecb1ccbcf29ab324cfd",
+      "environment_digest": "sha256:3e87402a84161471c1f8dc3d8b056f5831a309236751319831eb4ecb74b2a03b",
       "network_mode": "unenforced"
     }
   },
@@ -269,7 +269,7 @@
       "uri": "evaluation-output.json",
       "version": null,
       "schema_version": "1.0.0",
-      "digest": "sha256:18371c4465ff5300dffa9b5a3676e98d6676e11125427a79957f7ad7b20928e0"
+      "digest": "sha256:73c3a2c08d3ec835a9cea556277b820035cf0f6803c1b3e0c576609473229378"
     },
     "minimum_confidence": 1
   },