docs: add generated GitHub Pages handbook

.github/workflows/pages.yml

@@ -0,0 +1,71 @@
+name: Deploy documentation
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: github-pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: |
+            requirements-dev.txt
+            requirements-docs.txt
+
+      - name: Install dependencies
+        run: python -m pip install -r requirements-dev.txt -r requirements-docs.txt
+
+      - name: Validate repository
+        run: make validate
+
+      - name: Lint normative keywords
+        run: make validate-normative
+
+      - name: Generate documentation source
+        run: python tools/generate_site_docs.py
+
+      - name: Build documentation
+        run: mkdocs build
+
+      - name: Configure GitHub Pages
+        if: github.event_name != 'pull_request'
+        uses: actions/configure-pages@v5
+
+      - name: Upload GitHub Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: .site-build
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -7,3 +7,5 @@ venv/
 *.tmp
 *.swp
 *.zip
+.site-docs/
+.site-build/

MANIFEST.sha256

@@ -1,12 +1,12 @@
-3afa430e47b4b30640c8d21de565b90582f350249ab646c94ced96bf57e1a316  .gitignore
+b401b8ac1cc33a55f36f5faa2d8c4372cec56b980ad00c009dbca47eab0b41b8  .gitignore
 c81ae9ba64df3b1c5d9dcceed7e4f79d0a7ae4776380481b913149a08d99e309  ARCHITECTURE.md
 eb4ef0a34a5f941361972a7df4acc4a53007ab99a8773b95dd5a56c78091bea1  CHANGELOG.md
 a72fabcd2dd27e96394adbd633b71d9e403766336695ddd7e21257ae8c69dc01  CONFLICT-RESOLUTION.md
 d80cc0c8532a0c03869d10a6d09cebda54464af5337801af5fa528c4b2cdaba1  CONTRIBUTING.md
 83bd470cb3db0001eb905adeea0b55da1e121be5f1c5e0093a2c7b00bd69c971  DOCUMENTATION.md
 b70da374c6f05399968e77288de5db7f267e3c6b117d6c06cbdfc34168a43157  KNOWLEDGE-MODEL.md
 60f7cde752f96e821832576ed9ca9ddbd22efc0c3e6541a21e6a0605cf9ddb76  LICENSE
-eeebc06d9dcc1ec848136f44aad4b3105ab0987af8056826a6fbec3e97f1152c  Makefile
+b8047c1b1afe54e89a8086f04a43c44c36de72c472cf154e1e98527526c1bbfa  Makefile
 f83aba41dfb4e214e85536c8f055de4dd4de6c1593cdcef78cc0eb43d07f7cdd  README.md
 4567c3af0536e424f8dd62cae5adeae467f4b1f0b9723659609cf0791c126a06  ROADMAP.md
 75eef1e94056557516131f9d79aea0c8d9b92f102da74e44c08ec99496b69d2c  SELF-CONTAINMENT.md
@@ -400,6 +400,7 @@ b9687f0785ccd4f186cd27ab4e58eaddf37abc43da3d3eb6f905a3d1d860db33  schemas/resolv
 d55c4d1eb6edc1ecccbee5e6db1e0bea371919ad956cbc861caa30f32228e9a3  tools/distribution.py
 f12e52837e8b71dbc4436a2cf0a3a234f2c15823909b6c787d383451e454dcad  tools/evaluate.py
 f90fefe7940fb9438cfec6e163724407da5166e9826f54e57c8d67aaba01e7ba  tools/generate_compendium.py
+889d27abdf88b2695b57e864ad17de94376f2facfd03eb46ef27b5975fd52488  tools/generate_site_docs.py
 504558dd715c337641e86c194869d9d80f120183e9f0210043bb8385e89747ef  tools/orchestrate.py
 6b9ba027c38c88d567467bbbd52af1ec350cfa75a8825e798b0c9e6e2d771b89  tools/package.py
 0acadfba1a6044eabd532f285d7e673fba395537075c6468dc1ebb66493da10d  tools/update_manifest.py

Makefile

@@ -1,10 +1,18 @@
-.PHONY: evaluate generate test validate validate-normative manifest package resolve
+.PHONY: docs docs-serve evaluate generate test validate validate-normative manifest package resolve
 
 PYTHON ?= python3
 
 generate:
 	$(PYTHON) tools/generate_compendium.py
 
+docs:
+	$(PYTHON) tools/generate_site_docs.py
+	mkdocs build
+
+docs-serve:
+	$(PYTHON) tools/generate_site_docs.py
+	mkdocs serve
+
 test:
 	$(PYTHON) -m unittest discover -s tests -p 'test_*.py'
 

docs-site/index.md

@@ -0,0 +1,85 @@
+# Code Principles
+
+<div class="hero" markdown>
+
+## Engineering guidance that adapts to the project
+
+A self-contained, language-agnostic knowledge base and policy system for AI coding agents — presented here as a browsable engineering handbook.
+
+[Browse the 72 principles](principles/index.md){ .md-button .md-button--primary }
+[Explore the decision system](core/index.md){ .md-button }
+
+</div>
+
+<div class="home-grid" markdown>
+
+<div class="home-card" markdown>
+
+### Principles
+
+Canonical engineering ideas with explicit applicability, rejected interpretations, trade-offs, conflicts, examples, and AI guidance.
+
+[Browse principles →](principles/index.md)
+
+</div>
+
+<div class="home-card" markdown>
+
+### Core Skills
+
+Decision procedures that combine principles into practical modes for clarity, abstraction, testing, compatibility, reliability, performance, and more.
+
+[Explore Core Skills →](core/index.md)
+
+</div>
+
+<div class="home-card" markdown>
+
+### Project profiles
+
+Start from what you are building: application, library, service, worker, pipeline, plugin, prototype, CLI, real-time system, infrastructure tool, and more.
+
+[Choose a project profile →](profiles/index.md)
+
+</div>
+
+<div class="home-card" markdown>
+
+### Technology refinements
+
+See how generic policy is refined for JavaScript, TypeScript, Python, PHP, Go, C++, React, Next.js, Vue, Nuxt, Angular, Symfony, and Drupal.
+
+[Browse languages →](languages/index.md) · [Browse frameworks →](frameworks/index.md)
+
+</div>
+
+</div>
+
+## How the policy model works
+
+<div class="resolution-flow" role="list" aria-label="Policy resolution flow">
+  <div role="listitem"><strong>1</strong><span>Project evidence</span><small>task, repository, explicit context</small></div>
+  <div class="resolution-flow__arrow" aria-hidden="true">→</div>
+  <div role="listitem"><strong>2</strong><span>Project profile</span><small>dominant artifact and failure model</small></div>
+  <div class="resolution-flow__arrow" aria-hidden="true">→</div>
+  <div role="listitem"><strong>3</strong><span>Modifiers</span><small>verified cross-cutting constraints</small></div>
+  <div class="resolution-flow__arrow" aria-hidden="true">→</div>
+  <div role="listitem"><strong>4</strong><span>Core Skills</span><small>context-sensitive decision modes</small></div>
+  <div class="resolution-flow__arrow" aria-hidden="true">→</div>
+  <div role="listitem"><strong>5</strong><span>Technology adapters</span><small>language and framework semantics</small></div>
+  <div class="resolution-flow__arrow" aria-hidden="true">→</div>
+  <div role="listitem"><strong>6</strong><span>Resolved policy</span><small>explainable engineering decisions</small></div>
+</div>
+
+!!! info "The website is a generated view"
+    Canonical YAML and normative Markdown in the repository remain authoritative. This site is rebuilt from those sources and is never an independent source of policy.
+
+## Learn by example
+
+The repository includes executable evaluation scenarios that test profile selection, modifiers, language and framework refinements, conflict decisions, and forbidden overengineering. They are useful both as tests and as worked examples of the policy model.
+
+[Browse evaluation scenarios](evaluations/index.md){ .md-button }
+
+## Reference
+
+For the complete system contracts and architecture, continue with the [Specification](SPECIFICATION.md), [Architecture](ARCHITECTURE.md), [Knowledge Model](KNOWLEDGE-MODEL.md), and [Conflict Resolution](CONFLICT-RESOLUTION.md).

docs-site/javascripts/catalog-filter.js

@@ -0,0 +1,45 @@
+(() => {
+  const normalize = (value) => value.trim().toLocaleLowerCase();
+
+  const initCatalogFilters = () => {
+    document.querySelectorAll("[data-catalog-filter]").forEach((input) => {
+      if (input.dataset.catalogFilterReady === "true") return;
+      input.dataset.catalogFilterReady = "true";
+
+      const root = input.closest(".md-content") || document;
+      const items = Array.from(root.querySelectorAll("[data-catalog-item]"));
+      const count = root.querySelector("[data-catalog-count]");
+      const empty = root.querySelector("[data-catalog-empty]");
+
+      const apply = () => {
+        const query = normalize(input.value);
+        let visible = 0;
+
+        items.forEach((item) => {
+          const matches = !query || normalize(item.dataset.search || item.textContent || "").includes(query);
+          item.hidden = !matches;
+          if (matches) visible += 1;
+        });
+
+        root.querySelectorAll(".catalog-group").forEach((group) => {
+          const groupVisible = Array.from(group.querySelectorAll("[data-catalog-item]")).some((item) => !item.hidden);
+          group.hidden = !groupVisible;
+        });
+
+        if (count) count.textContent = `${visible} ${visible === 1 ? "entry" : "entries"}`;
+        if (empty) empty.hidden = visible !== 0;
+      };
+
+      input.addEventListener("input", apply);
+      apply();
+    });
+  };
+
+  if (typeof document$ !== "undefined") {
+    document$.subscribe(initCatalogFilters);
+  } else if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initCatalogFilters);
+  } else {
+    initCatalogFilters();
+  }
+})();