fix: keep navigation active on deep documentation pages

MANIFEST.sha256

@@ -398,6 +398,7 @@ c3068c7a08e7f2ae0cc0328323937a78a677acf7c25ca714c01b54d670882f81  schemas/projec
 b9687f0785ccd4f186cd27ab4e58eaddf37abc43da3d3eb6f905a3d1d860db33  schemas/resolved-policy.schema.json
 05936f498fac344084227cfd19ab717c308fb1dd47cfd42cd6fa5c4baa16b478  schemas/skill.schema.json
 d55c4d1eb6edc1ecccbee5e6db1e0bea371919ad956cbc861caa30f32228e9a3  tools/distribution.py
+cbfa65a3813a7a5bc1cb7ac1276faaab31d3ab7c2463c51bbeff22145091c1d2  tools/docs_nav.py
 f12e52837e8b71dbc4436a2cf0a3a234f2c15823909b6c787d383451e454dcad  tools/evaluate.py
 f90fefe7940fb9438cfec6e163724407da5166e9826f54e57c8d67aaba01e7ba  tools/generate_compendium.py
 0c062fd50ccf31fdcbbd37538570cca4b85bd4026f6be6909454c7dc9f1c8753  tools/generate_site_docs.py

docs-site/decision-system/index.md

@@ -0,0 +1,48 @@
+# Decision system
+
+See how Code Principles turns canonical engineering knowledge into context-sensitive decisions.
+
+<div class="home-grid" markdown>
+
+<div class="home-card" markdown>
+
+### Core Skills
+
+Language-independent decision procedures with modes, conflicts, constraints, and review guidance.
+
+[Browse Core Skills →](../core/index.md)
+
+</div>
+
+<div class="home-card" markdown>
+
+### Project profiles
+
+Select the dominant artifact and failure model before technology-specific refinements are applied.
+
+[Browse project profiles →](../profiles/index.md)
+
+</div>
+
+<div class="home-card" markdown>
+
+### Modifiers
+
+Apply verified cross-cutting constraints such as public API, security sensitivity, latency, or compatibility requirements.
+
+[Browse modifiers →](../modifiers/index.md)
+
+</div>
+
+<div class="home-card" markdown>
+
+### Resolution rules
+
+Understand precedence, conflict resolution, and the orchestrator that combines the policy layers.
+
+[Conflict resolution →](../CONFLICT-RESOLUTION.md)  
+[Orchestrator →](../orchestrator/SKILL.md)
+
+</div>
+
+</div>

docs-site/examples/index.md

@@ -0,0 +1,17 @@
+# Examples
+
+Worked, executable examples show how repository evidence, project profiles, modifiers, adapters, Skill modes, and conflict decisions combine into resolved engineering policy.
+
+<div class="home-grid" markdown>
+
+<div class="home-card" markdown>
+
+### Evaluation scenarios
+
+Browse generated human-readable views of the repository's executable policy scenarios. Each page shows the input evidence, expected resolution, tested principles, and forbidden outcomes.
+
+[Browse evaluation scenarios →](../evaluations/index.md)
+
+</div>
+
+</div>

docs-site/reference/index.md

@@ -0,0 +1,52 @@
+# Reference
+
+System-level contracts, architecture, terminology, and project documentation for Code Principles.
+
+<div class="home-grid" markdown>
+
+<div class="home-card" markdown>
+
+### System contracts
+
+Start with the normative specification and the architecture that defines how the knowledge base and resolver fit together.
+
+[Specification →](../SPECIFICATION.md)  
+[Architecture →](../ARCHITECTURE.md)
+
+</div>
+
+<div class="home-card" markdown>
+
+### Knowledge model
+
+Understand classifications, terminology, precedence, and the self-containment rules behind the project.
+
+[Knowledge model →](../KNOWLEDGE-MODEL.md)  
+[Terminology →](../TERMINOLOGY.md)  
+[Self-containment →](../SELF-CONTAINMENT.md)
+
+</div>
+
+<div class="home-card" markdown>
+
+### Repository
+
+Read the project overview or contribute changes to the knowledge base and tooling.
+
+[Repository overview →](../README.md)  
+[Contributing →](../CONTRIBUTING.md)
+
+</div>
+
+<div class="home-card" markdown>
+
+### Project history
+
+See planned work and changes across releases.
+
+[Roadmap →](../ROADMAP.md)  
+[Changelog →](../CHANGELOG.md)
+
+</div>
+
+</div>

docs-site/technologies/index.md

@@ -0,0 +1,27 @@
+# Technologies
+
+Language and framework adapters refine generic engineering policy with concrete runtime, lifecycle, packaging, state, and convention semantics.
+
+<div class="home-grid" markdown>
+
+<div class="home-card" markdown>
+
+### Languages
+
+JavaScript, TypeScript, Python, PHP, Go, and C++ adapters refine the generic policy without redefining canonical principles.
+
+[Browse language adapters →](../languages/index.md)
+
+</div>
+
+<div class="home-card" markdown>
+
+### Frameworks
+
+React, Next.js, Angular, Vue, Nuxt, Symfony, and Drupal adapters add framework-specific boundaries, lifecycle, state, and extension guidance.
+
+[Browse framework adapters →](../frameworks/index.md)
+
+</div>
+
+</div>

mkdocs.yml

@@ -8,33 +8,8 @@ docs_dir: .site-docs
 site_dir: .site-build
 use_directory_urls: true
 
-nav:
-  - Home: index.md
-  - Principles:
-      - Browse principles: principles/index.md
-      - Classification: principles/CLASSIFICATION.md
-      - Authoring guide: principles/AUTHORING-GUIDE.md
-  - Decision system:
-      - Core Skills: core/index.md
-      - Project profiles: profiles/index.md
-      - Modifiers: modifiers/index.md
-      - Conflict resolution: CONFLICT-RESOLUTION.md
-      - Orchestrator: orchestrator/SKILL.md
-  - Technologies:
-      - Languages: languages/index.md
-      - Frameworks: frameworks/index.md
-  - Examples:
-      - Evaluation scenarios: evaluations/index.md
-  - Reference:
-      - Repository overview: README.md
-      - Specification: SPECIFICATION.md
-      - Architecture: ARCHITECTURE.md
-      - Knowledge model: KNOWLEDGE-MODEL.md
-      - Terminology: TERMINOLOGY.md
-      - Self-containment: SELF-CONTAINMENT.md
-      - Contributing: CONTRIBUTING.md
-      - Roadmap: ROADMAP.md
-      - Changelog: CHANGELOG.md
+hooks:
+  - tools/docs_nav.py
 
 theme:
   name: material

tools/docs_nav.py

@@ -0,0 +1,116 @@
+"""Generate MkDocs navigation from the repository's canonical metadata.
+
+This hook keeps generated documentation pages inside the Material navigation tree so
+active tabs and side navigation remain available on deep pages without maintaining a
+large static nav block by hand.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def load_yaml(path: Path):
+    return yaml.safe_load(path.read_text(encoding="utf-8"))
+
+
+def component_pages(directory: str, metadata_name: str) -> list[dict[str, str]]:
+    pages: list[dict[str, str]] = []
+    for metadata in sorted((ROOT / directory).glob(f"*/{metadata_name}")):
+        data = load_yaml(metadata) or {}
+        item_id = data.get("id", metadata.parent.name)
+        name = data.get("name") or item_id.replace("-", " ").title()
+        pages.append({str(name): f"{directory}/{item_id}/index.md"})
+    return sorted(pages, key=lambda item: next(iter(item)).casefold())
+
+
+def principle_catalogue() -> list[dict[str, list[dict[str, str]]]]:
+    registry = load_yaml(ROOT / "principles" / "registry.yaml") or {}
+    categories_data = load_yaml(ROOT / "principles" / "categories.yaml") or {}
+    principles = registry.get("principles") or []
+
+    categories = [
+        (category["id"], category["name"])
+        for category in categories_data.get("categories") or []
+    ]
+
+    groups: list[dict[str, list[dict[str, str]]]] = []
+    for category_id, category_name in categories:
+        entries = [item for item in principles if item.get("category") == category_id]
+        if not entries:
+            continue
+        pages = [
+            {str(item["name"]): f"principles/compendium/{item['id']}.md"}
+            for item in sorted(entries, key=lambda value: str(value["name"]).casefold())
+        ]
+        groups.append({str(category_name): pages})
+    return groups
+
+
+def evaluation_pages() -> list[dict[str, str]]:
+    pages: list[dict[str, str]] = []
+    for path in sorted((ROOT / "evaluations" / "scenarios").glob("*.yaml")):
+        data = load_yaml(path) or {}
+        scenario_id = data.get("id", path.stem)
+        title = data.get("name") or data.get("title") or scenario_id.replace("-", " ").title()
+        pages.append({str(title): f"evaluations/{scenario_id}/index.md"})
+    return sorted(pages, key=lambda item: next(iter(item)).casefold())
+
+
+def build_nav():
+    return [
+        {"Home": "index.md"},
+        {
+            "Principles": [
+                "principles/index.md",
+                {"Catalogue": principle_catalogue()},
+                {"Classification": "principles/CLASSIFICATION.md"},
+                {"Authoring guide": "principles/AUTHORING-GUIDE.md"},
+            ]
+        },
+        {
+            "Decision system": [
+                "decision-system/index.md",
+                {"Core Skills": ["core/index.md", *component_pages("core", "skill.yaml")]},
+                {"Project profiles": ["profiles/index.md", *component_pages("profiles", "profile.yaml")]},
+                {"Modifiers": ["modifiers/index.md", *component_pages("modifiers", "modifier.yaml")]},
+                {"Conflict resolution": "CONFLICT-RESOLUTION.md"},
+                {"Orchestrator": "orchestrator/SKILL.md"},
+            ]
+        },
+        {
+            "Technologies": [
+                "technologies/index.md",
+                {"Languages": ["languages/index.md", *component_pages("languages", "adapter.yaml")]},
+                {"Frameworks": ["frameworks/index.md", *component_pages("frameworks", "adapter.yaml")]},
+            ]
+        },
+        {
+            "Examples": [
+                "examples/index.md",
+                {"Evaluation scenarios": ["evaluations/index.md", *evaluation_pages()]},
+            ]
+        },
+        {
+            "Reference": [
+                "reference/index.md",
+                {"Repository overview": "README.md"},
+                {"Specification": "SPECIFICATION.md"},
+                {"Architecture": "ARCHITECTURE.md"},
+                {"Knowledge model": "KNOWLEDGE-MODEL.md"},
+                {"Terminology": "TERMINOLOGY.md"},
+                {"Self-containment": "SELF-CONTAINMENT.md"},
+                {"Contributing": "CONTRIBUTING.md"},
+                {"Roadmap": "ROADMAP.md"},
+                {"Changelog": "CHANGELOG.md"},
+            ]
+        },
+    ]
+
+
+def on_config(config, **kwargs):
+    config["nav"] = build_nav()
+    return config