From b65d3599a347431e822e9777286dedd7ad7b94d7 Mon Sep 17 00:00:00 2001
From: Piotr Ramotowski <8025853+PeterRamotowski@users.noreply.github.com>
Date: Wed, 2 Sep 2026 09:33:23 +0200
Subject: [PATCH 1/9] docs: generate complete navigation tree
---
tools/docs_nav.py | 116 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 116 insertions(+)
create mode 100644 tools/docs_nav.py
diff --git a/tools/docs_nav.py b/tools/docs_nav.py
new file mode 100644
index 0000000..fe0cd04
--- /dev/null
+++ b/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
From 99873d3a7aea9d7e58a6dec75e1a42b3b439cd2c Mon Sep 17 00:00:00 2001
From: Piotr Ramotowski <8025853+PeterRamotowski@users.noreply.github.com>
Date: Wed, 2 Sep 2026 09:33:37 +0200
Subject: [PATCH 2/9] docs: drive navigation from metadata hook
---
mkdocs.yml | 29 ++---------------------------
1 file changed, 2 insertions(+), 27 deletions(-)
diff --git a/mkdocs.yml b/mkdocs.yml
index a128f6a..455bccd 100644
--- a/mkdocs.yml
+++ b/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
From bd59497714c62183c1bc3e75380f00e7770a0f57 Mon Sep 17 00:00:00 2001
From: Piotr Ramotowski <8025853+PeterRamotowski@users.noreply.github.com>
Date: Wed, 2 Sep 2026 09:33:54 +0200
Subject: [PATCH 3/9] docs: add Reference landing page
---
docs-site/reference/index.md | 52 ++++++++++++++++++++++++++++++++++++
1 file changed, 52 insertions(+)
create mode 100644 docs-site/reference/index.md
diff --git a/docs-site/reference/index.md b/docs-site/reference/index.md
new file mode 100644
index 0000000..1c9f7f5
--- /dev/null
+++ b/docs-site/reference/index.md
@@ -0,0 +1,52 @@
+# Reference
+
+System-level contracts, architecture, terminology, and project documentation for Code Principles.
+
+
+
+
+
+### 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)
+
+
+
+
+
+### 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)
+
+
+
+
+
+### Repository
+
+Read the project overview or contribute changes to the knowledge base and tooling.
+
+[Repository overview →](../README.md)
+[Contributing →](../CONTRIBUTING.md)
+
+
+
+
+
+### Project history
+
+See planned work and changes across releases.
+
+[Roadmap →](../ROADMAP.md)
+[Changelog →](../CHANGELOG.md)
+
+
+
+
+
+
+
+### Core Skills
+
+Language-independent decision procedures with modes, conflicts, constraints, and review guidance.
+
+[Browse Core Skills →](../core/index.md)
+
+
+
+
+
+### Project profiles
+
+Select the dominant artifact and failure model before technology-specific refinements are applied.
+
+[Browse project profiles →](../profiles/index.md)
+
+
+
+
+
+### Modifiers
+
+Apply verified cross-cutting constraints such as public API, security sensitivity, latency, or compatibility requirements.
+
+[Browse modifiers →](../modifiers/index.md)
+
+
+
+
+
+### Resolution rules
+
+Understand precedence, conflict resolution, and the orchestrator that combines the policy layers.
+
+[Conflict resolution →](../CONFLICT-RESOLUTION.md)
+[Orchestrator →](../orchestrator/SKILL.md)
+
+
+
+
+
+
+
+### Languages
+
+JavaScript, TypeScript, Python, PHP, Go, and C++ adapters refine the generic policy without redefining canonical principles.
+
+[Browse language adapters →](../languages/index.md)
+
+
+
+
+
+### 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)
+
+
+
+
+
+
+
+### 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)
+
+
+
+