LLM Wiki — Approach

Open Decisions

None — all resolved.

Resolved: Source Ingestion Model

Source pages (.ai/ docs, repo READMEs, repo docs folders) are ingested directly into the static site at build time via scripts/ingest-sources.sh. They are NOT stored in the wiki repo — the content/sources/ directory is .gitignored and populated fresh on each build.

This means:

Source docs are browsable in the wiki alongside synthesized wiki pages
No duplication in the wiki git repo — sources stay at their origin
The build script copies all markdown from .ai/, all repo READMEs, and docs folders
Quartz renders them with the same graph view, backlinks, and search as wiki pages
The wiki’s synthesized pages can wikilink to source docs (e.g. [[sources/ai/projects/cascadeguard/adr/001|ADR-001]])

Concept

A git-backed, AI-maintained knowledge system in its own repository. The wiki is a synthesis layer — it does not duplicate content that already exists in git. It does pull and synthesize content from external systems (Paperclip issues, GitHub issues/PRs) that don’t have a git-native home. For git-backed sources, wiki pages reference source paths + SHAs and provide cross-linked summaries.

Key Principles

Everything is a reference (for git content). Records, ADRs, incidents, state docs — the wiki synthesizes and cross-links, pointing to source paths + git SHAs + repo identifiers (e.g., craigedmunds/workspace-root). Content from non-git systems (Paperclip, GitHub Issues) may be pulled in as it has no stable file-based home.
Source files are the truth. The wiki is a derived view. If a source file changes, the wiki reflects that at next ingest.
Review via PRs. AI creates branches and opens PRs for proposed changes. Humans review, comment, iterate, and merge. No custom proposal queue.
Broader than .ai/. Sources include:
- All markdown files from all repos, especially READMEs
- cascadeguard-docs documentation
- thelongrun-publishing docs folder (docs/) and content (src/content/)
- 45+ Paperclip issues, GitHub PRs/issues
- Code-level source files excluded.
Human-consumable output. Static site via Quartz with graph view + flat docs.
Organisation structure as source. /workspace/organisation.md defines the organisational hierarchy — projects, repos (with GitHub URLs and PVC paths), teams, and their relationships. This is both a primary source for the wiki AND informs how wiki content is structured.

The Reference Model

How State Works (Pointer + SHA)

State pages (e.g. “what is the Image Factory today?”) contain a synthesis with source pointers:

---
id: image-factory-system
type: state
sources:
  - repo: craigedmunds/image-factory
    path: README.md
    sha: a3f7c2e
  - repo: craigedmunds/workspace-root
    path: .ai/projects/infrastructure/image-factory/spec.md
    sha: 8b2d1f4
---
 
## Image Factory
 
Automated container image building and promotion using Kargo and ArgoCD with CDK8s. Now subsumed into CascadeGuard.
 
**Current state:** Being migrated to CascadeGuard CLI...
**Key references:**
- Project spec @ a3f7c2e (workspace-root)
- Image Factory repo — CDK8s, TypeScript

When the source SHA changes, the lint process flags the page as stale and proposes an update PR.

How Records Work (Pure Pointers)

ADRs, incidents, and decisions are NOT stored in the wiki. The wiki maintains index pages linking to where records live. Cross-references added (e.g., linking an ADR to related system pages) but record bodies stay at source.

How Projects Work

Project pages are a first-class wiki concept representing organisational boundaries as defined in organisation.md. The key distinction:

Projects = organisational units from organisation.md (e.g., CascadeGuard, Market Making, Development Tools, The Long Run, EE-HMRC-EIS)
Systems = deployable technical components within projects (e.g., Paperclip, ArgoCD, Image Factory, k8s-lab)

A project may contain multiple systems, and systems may be shared across projects by exception.

---
id: cascadeguard
type: project
sources:
  - repo: craigedmunds/workspace-root
    path: .ai/projects/cascadeguard/
    sha: d4e8f1a
  - repo: craigedmunds/workspace-root
    path: organisation.md
    sha: b7c3e2f
---
 
## CascadeGuard
 
Container security lifecycle platform.
 
**People:** CTO, CMO, Product Owner, Platform Engineer, Full-Stack Dev, DevSecOps (11 agent roles via BMAD)
**Repos (OSS):** cascadeguard, cascadeguard-docs, cascadeguard-actions, cascadeguard-open-secure-images, cascadeguard-exemplar, cascadeguard-exemplar-web-argocd, cascadeguard-seed
**Repos (Corp):** cascadeguard-app, cascadeguard-data, cascadeguard-org
**Cross-project:** May interact with k8s-lab, ai-dev, and other Techcle projects by exception
**Paperclip issues:** [linked from index]
**Key decisions:** [[decisions/cascadeguard-adr-001]], [[decisions/cascadeguard-adr-005]]
**Status:** Active — 5 ADRs, PRDs, designer briefs, multi-repo CI

Projects map:

People — which agents/roles work on this
Repos (OSS / Corp) — grouped by purpose, not frequency
Cross-project — which other projects this touches by exception
Issues — Paperclip and GitHub issues related to this project
Decisions — ADRs and key decisions
Current status — synthesized from recent activity

How the Organisation Structure Feeds the Wiki

The organisation document (/workspace/organisation.md) provides:

Project hierarchy — Techcle → Consulting / Other Technology / Personal. This maps directly to wiki project pages and navigation structure.
Repo-to-project mapping — Which repos belong to which project, with GitHub URLs and PVC paths. Drives the indexes/repositories.md page and per-project repo lists.
Team composition — Which agents work on which project. Drives the indexes/agents.md page and per-project people sections.
Business context — Consulting vs product vs personal classification helps the wiki surface relevant cross-references.

When organisation.md changes, the wiki lint process detects the SHA change and proposes updates to all affected project pages.

Architecture

Build / Serve Split (v6)

Build (runs in container/sidecar(s), storage is PVC):

Source: repos/wiki/content/ (wiki markdown + ingested sources)
Config: repos/wiki/quartz.config.ts
Scripts: repos/wiki/scripts/ingest-sources.sh
Output: repos/wiki/dist/ (BUILD OUTPUT, gitignored)

Build command (Taskfile targets — executed by sidecar(s) but can also run outside for testing):

cd /workspace/repos/wiki
./scripts/ingest-sources.sh (populate content/sources/)
npx quartz build -o dist (build static site to dist/)

Serve (dedicated pod): nginx:alpine pod mounts PVC, serves /workspace/repos/wiki/dist/.

No image rebuild needed when content changes. Sidecar(s) run the build tasks on PVC, nginx serves new files immediately.

Why Quartz Is Still Right

The “server component” is just a static file server (nginx). Quartz’s key features are all client-side:

Graph view — client-side D3 visualization
Full-text search — client-side FlexSearch index built at compile time
SPA navigation — client-side router for fast page transitions
Backlinks & popovers — computed at build time, rendered client-side

Alternatives considered:

MkDocs Material — Good docs tool but no graph view, no wikilinks, no backlinks
Docusaurus — React-heavy, no graph view, designed for product docs not wikis
Wiki.js — Full server-rendered wiki, overkill, requires database, loses git-native simplicity
Quartz 4 (chosen) — Static output, all wiki features client-side, any server can host it

Pod Architecture (Dojo Pattern)

Follows the same pattern as dojo: ArgoCD seed + k8s manifests in the repo.

Deployment: wiki pod in code-server namespace

Container: nginx:alpine (never needs rebuilding, 2MB image)
Port: 80
Volume: code-server-storage PVC mounted read-only at /workspace
ConfigMap: wiki-nginx-config for SPA routing

nginx config:

Root: /workspace/repos/wiki/dist
try_files for SPA fallback ($uri, $uri/index.html, $uri.html, 404)
Cache static assets (css, js, images) for 1 day

Service + Ingress follow the dojo pattern with ArgoCD seed/spoon:

wiki.lab.ctoaas.co — public, authenticated (standard ingress helm chart pattern)
wiki.lab.local.ctoaas.co — local, no auth

Rebuild Flow

Content update → rebuild → nginx serves new files (no pod restart needed):

task wiki:build (runs ingest + quartz build to dist/)
For automated rebuilds: cronjob or cron in a sidecar pod (not Paperclip). The Kiro agent (see TEC-78) may handle this from a sidecar container.

Separate Repository

The wiki lives in /workspace/repos/wiki/ as its own git repo. Benefits:

Clean git history — wiki changes don’t pollute source repos
PR-based review — standard GitHub workflow
Clear separation of synthesis from source

Source Ingestion (Build-Time)

Source documents are ingested at build time by scripts/ingest-sources.sh:

Copies all .ai/ markdown → content/sources/ai/ (preserving directory structure)
Copies repo READMEs → content/sources/repos/{repo-name}/index.md
Copies repo docs/ folders → content/sources/repos/{repo-name}/docs/
Copies organisation.md → content/sources/organisation.md
Adds frontmatter (title, tags) to files that lack it
Excludes secrets files

content/sources/ is excluded from git via .git/info/exclude (not .gitignore, because Quartz’s globby respects .gitignore and would skip the files). Never committed to the wiki repo. Build order: ingest → quartz build → flatten-urls → deploy.

Source Map (`sources.yaml`)

Declares all content sources with their classification:

organisation.md — Organisational hierarchy. Primary source for project structure, repo mappings, team composition.

.ai/projects/ — 16 infrastructure subprojects, 11 cascadeguard subprojects, 10 market-making, 8 ai-dev, 5 domain-apis, plus hip, tri-training, thelongrun, nutrition-tracker, eda, systemsx, devsec.

.ai/steering/ — 18 living state documents (workflows, standards, policies).

.ai/agents/ — 20+ agent roles with AGENTS.md, JOB_DESCRIPTION.md, identity.yaml, HEARTBEAT.md, SOUL.md, memory/. Exclude .secrets.yaml.

.ai/skills/ — 11 skill definitions.

.ai/ root — README.md, SCHEMA.md, INDEX.md (stale), projectlist.md.

Repo markdown files — READMEs from all 27+ repos. Full docs from cascadeguard-docs, thelongrun-publishing (docs/ and src/content/). All markdown files from all repos.

27+ repositories — git metadata (PRs merged, descriptions, tech stacks). No code files.

Paperclip issues — 45+ issues across all statuses. Descriptions, comments, goal context, project associations.

GitHub issues/PRs — from active repos.

Wiki Structure

wiki/                          # /workspace/repos/wiki/
├── quartz.config.ts           # Quartz configuration
├── content/                   # All wiki content (Quartz convention)
│   ├── index.md               # Landing page / master catalog
│   ├── sources.yaml           # Source map
│   ├── log.md                 # Append-only activity log
│   ├── organisation/          # Org hierarchy pages (from organisation.md)
│   │   ├── techcle.md
│   │   ├── consulting.md
│   │   └── personal.md
│   ├── projects/              # Project pages (org boundaries from organisation.md)
│   │   ├── cascadeguard.md
│   │   ├── market-making.md
│   │   ├── development-tools.md
│   │   ├── ee-hmrc-eis.md
│   │   ├── thelongrun.md
│   │   ├── triathlon.md
│   │   └── nutrition.md
│   ├── systems/               # Per-system state pages (deployable components)
│   │   ├── paperclip.md
│   │   ├── cascadeguard.md
│   │   ├── argocd.md
│   │   ├── image-factory.md
│   │   ├── k8s-lab.md
│   │   ├── ai-dev.md
│   │   ├── backstage.md
│   │   ├── domain-apis.md
│   │   └── hip.md
│   ├── products/              # Commercial / public-facing products
│   │   ├── cascadeguard-oss.md
│   │   ├── cascadeguard-premium.md
│   │   ├── market-making.md
│   │   └── thelongrun.md
│   ├── operations/
│   │   ├── deployment-patterns.md
│   │   └── security-posture.md
│   ├── indexes/               # Derived, fully regenerable
│   │   ├── repositories.md
│   │   ├── agents.md
│   │   ├── decisions.md
│   │   ├── standards.md
│   │   ├── issues.md
│   │   └── topics/
│   └── templates/             # Page templates for consistency
├── dist/                      # Quartz build output (gitignored, served by nginx pod)
└── k8s/                       # K8s manifests (deployment, service, configmap, kustomization)

SSG: Quartz 4

Quartz — static-site generator designed for knowledge wikis:

Graph view — interactive visualization of page connections
Flat docs — standard markdown files
Backlinks — automatic bi-directional linking
Wikilinks — [[page-name]] syntax for cross-referencing
Full-text search — built-in client-side search
Popover previews — hover to preview linked pages
Node v22 compatible

PR-Based Review Workflow

AI creates a branch (e.g. ingest/cascadeguard-update-apr19)
AI commits proposed wiki changes to the branch
AI opens a PR with: what changed, why, confidence level, source references
Human reviews, comments, iterates
Human approves and merges
Over time, high-confidence PRs may auto-merge

Confidence levels:

Level	Meaning	PR Action
high	Factual, derived directly from source	Auto-merge candidate (once trust established)
medium	Synthesized from multiple sources	Standard review
low	Interpretation or sparse evidence	Detailed review required

Execution Model

Tooling

Taskfile — orchestrates wiki build steps (repo sync, ingest, lint, Quartz build)
Wiki worktree — /workspace/.builders/wiki/ provides a clean build environment isolated from other tasks
Agent(s) and skill(s) — Claude Code agent manages the ingest/synthesis process via Paperclip skills
Taskfile and job live in k8s-lab as a wiki component

Repo Sync

The Taskfile ensures:

All repos listed in organisation.md are present in the worktree (if a new repo appears on the PVC in /workspace/repos/, include it)
All repos are on latest origin/main
Submodules (if used) are updated

Scheduling

Cronjob or cron in sidecar pod — runs the full ingest/lint/build cycle
Kiro agent (TEC-78) may run in a Docker container as a sidecar to manage this
Staleness detection runs as part of the build cycle

Implementation Phases

Phase 1: Foundation + Full Source Ingest

Create wiki repo at /workspace/repos/wiki/ with Quartz scaffold
Set up sources.yaml — declare all source paths and classifications, including organisation.md
Set up Taskfile in k8s-lab — wiki component with repo sync, ingest, build tasks
Create wiki worktree at /workspace/.builders/wiki/
Ingest all sources including issues:
- Organisation structure (organisation.md) — project hierarchy, repo mappings, teams
- All 45+ Paperclip issues (descriptions, comments, status, goals)
- GitHub issues/PRs from active repos
- All .ai/ content (projects, steering, agents, skills)
- All repo markdown (READMEs, cascadeguard-docs, thelongrun docs/content)
- All 27+ repo git metadata (PRs merged, descriptions, tech stacks)
Seed pages:
- organisation/techcle.md — top-level org overview derived from organisation.md
- projects/cascadeguard.md — best-documented project (8+ repos OSS/Corp, 11 roles, ADRs, PRDs)
- projects/development-tools.md — platform project spanning k8s-lab, ai-dev, paperclip, etc.
- systems/cascadeguard.md — system state page
- systems/paperclip.md — system state page
- products/cascadeguard-oss.md — open-source product page
- products/cascadeguard-premium.md — commercial product page
- indexes/repositories.md — all 27+ repos with org-level classification, GitHub URLs, PVC paths
- indexes/decisions.md — ADR index
- indexes/issues.md — issue index from Paperclip + GitHub
Quartz config — graph view, backlinks, search, wikilinks enabled
Build and deploy — task wiki:build outputs to repos/wiki/dist/ (gitignored)
K8s manifests — nginx:alpine deployment, service, configmap, ingress (dojo pattern)
ArgoCD seed — Application seed pointing at repos/wiki/k8s/base/
First PR — submit all seed content as a PR for review

Phase 2: Broader Coverage

Process remaining projects (EE-HMRC-EIS workstreams, Market Making, personal projects)
Generate system pages for all active infrastructure
Expand project pages with deeper people/repo/issue mappings
Topic hub pages (kubernetes, gitops, security, trading, etc.)
Full org hierarchy pages (consulting, personal, each engagement)

Phase 3: Maintenance + Trust Building

Sidecar cronjob for periodic ingest + staleness detection (SHA comparison)
Kiro agent (TEC-78) manages rebuild scheduling from sidecar container
Lint: flag wiki pages whose source SHAs have changed (including organisation.md)
Auto-PR for stale pages
Gradual auto-merge for high-confidence changes

Staleness Detection

Each wiki page records source git SHAs and repo identifiers
Lint compares stored SHAs against current HEAD of each repo
Changed SHAs trigger a re-ingest PR
Confidence level depends on nature of change

Resolved Questions

Question	Resolution
SSG choice	Quartz 4 — flat docs + graph view + backlinks + search
Review UX	GitHub PRs on the wiki repo
Git tracking	Own repo — wiki has its own git history at /workspace/repos/wiki/
Separate repo	Yes — cleaner than workspace-root, enables PR review
Issues in scope	Yes Phase 1 — all Paperclip issues + GitHub issues/PRs
Projects concept	Yes — first-class project pages mapping people, repos, issues
Org structure	Yes — organisation.md as primary source for project hierarchy and wiki structure
Projects vs Systems	Distinct concepts — projects = org boundaries, systems = deployable components
Repo classification	OSS vs Corp for CascadeGuard; cross-project interactions noted separately
Products	CascadeGuard OSS + Premium are products; ai-dev is a system
Execution	Taskfile + worktree in k8s-lab, sidecar cronjob, Kiro agent (TEC-78)
Build output	`repos/wiki/dist/` — gitignored, not `files/ai-wiki/`
Serving	nginx:alpine pod on PVC (dojo pattern) — content from PVC, no image rebuilds
Quartz with server?	Yes, still best — all wiki features are client-side JS; server is just nginx
Hostname	Dual — `wiki.lab.ctoaas.co` (public, auth) + `wiki.lab.local.ctoaas.co` (local, no auth)
Authentication	Standard ingress helm chart pattern — local no auth, public auth
Rebuild trigger	Sidecar cron — Kiro agent in Docker container/sidecar (TEC-78), not Paperclip
Build execution	In container/sidecar(s) — Taskfile targets, runnable outside for testing

Techcle Wiki

Explorer

Approach

LLM Wiki — Approach

Open Decisions

Resolved: Source Ingestion Model

Concept

Key Principles

The Reference Model

How State Works (Pointer + SHA)

How Records Work (Pure Pointers)

How Projects Work

How the Organisation Structure Feeds the Wiki

Architecture

Build / Serve Split (v6)

Why Quartz Is Still Right

Pod Architecture (Dojo Pattern)

Rebuild Flow

Separate Repository

Source Ingestion (Build-Time)

Source Map (`sources.yaml`)

Wiki Structure

SSG: Quartz 4

PR-Based Review Workflow

Execution Model

Tooling

Repo Sync

Scheduling

Implementation Phases

Phase 1: Foundation + Full Source Ingest

Phase 2: Broader Coverage

Phase 3: Maintenance + Trust Building

Staleness Detection

Resolved Questions

Graph View

Table of Contents

Techcle Wiki

Explorer

Approach

LLM Wiki — Approach

Open Decisions

Resolved: Source Ingestion Model

Concept

Key Principles

The Reference Model

How State Works (Pointer + SHA)

How Records Work (Pure Pointers)

How Projects Work

How the Organisation Structure Feeds the Wiki

Architecture

Build / Serve Split (v6)

Why Quartz Is Still Right

Pod Architecture (Dojo Pattern)

Rebuild Flow

Separate Repository

Source Ingestion (Build-Time)

Source Map (sources.yaml)

Wiki Structure

SSG: Quartz 4

PR-Based Review Workflow

Execution Model

Tooling

Repo Sync

Scheduling

Implementation Phases

Phase 1: Foundation + Full Source Ingest

Phase 2: Broader Coverage

Phase 3: Maintenance + Trust Building

Staleness Detection

Resolved Questions

Graph View

Table of Contents

Source Map (`sources.yaml`)