# Wiki Schema ## Domain Strictly limited to three focus areas: 1. **AI Engineering** (model architectures, context engineering, LLM infrastructure, fine-tuning, RAG vs wiki, evaluations, inference). 2. **Science** (first-principles physics/computation, scientific inquiry, pedagogy, Feynman techniques). 3. **Agentic Engineering Patterns** (autonomous agents, multi-agent workflows, TDD with agents, coding conduct, tool use, memory/context orchestration). **Negative Scope (Strict Filter):** Do NOT ingest, create pages for, or file notes about arbitrary research topics (personal lifestyle, general news, random IT/devops trivia, unrelated apps/frameworks, product comparisons outside AI/science/agents) into this wiki. **Zero Harness Pollution (Boundary Invariant):** Internal agent harness details (host filesystem paths like `/opt/data`, VPS container layout, port configurations, internal persona structures from `SOUL.md`, private agent memories from `MEMORY.md`, and unvetted scratch notes) MUST NEVER be ingested into `pyweb/wiki/`. Canonical wiki entries must be synthesized exclusively from verifiable external primary sources in `raw/`. ## Conventions - File names: lowercase, hyphens, no spaces (e.g., `feynman-technique.md`) - Every wiki page starts with YAML frontmatter (see below) - Use wikilinks syntax (for example: `[[concept-slug]]` or `[[concept-slug|Display Text]]`) to link between pages (minimum 2 outbound links per page) - When updating a page, always bump the `updated` date - Every new page must be added to `index.md` under the correct section - Every action must be appended to `log.md` - Provenance markers: on pages that synthesize 3+ sources, append `^[raw/articles/source-file.md]` at the end of paragraphs whose claims come from a specific source. ## Frontmatter ```yaml --- title: Page Title created: YYYY-MM-DD updated: YYYY-MM-DD type: entity | concept | comparison | query | summary tags: [from taxonomy below] sources: [raw/articles/source-name.md] confidence: high | medium | low # optional contested: true # optional contradictions: [other-page-slug] # optional --- ``` ### raw/ Frontmatter ```yaml --- source_url: https://... ingested: YYYY-MM-DD sha256: --- ``` ## Tag Taxonomy - People/Orgs: person, educator, physicist, company, organization, authority - Persona: persona, voice, worldview, teaching - Engineering process: workflow, tdd, code-review, triage, spec, tickets, anti-patterns, git, architecture, code-quality, patterns - AI-era engineering: agents, agentic-patterns, context-engineering, coding-guidelines, feedback-loops, subagents, evaluation, principle, skills, diagrams, security, harness-engineering, llm-fundamentals, llm-infrastructure, tool-use, protocols, benchmarks - Application quality: quality, cost, roles - Learning: pedagogy, technique, knowledge-management, visual-explanation - Meta: comparison, principle, retrospective Rule: every tag on a page must appear in this taxonomy. Add new tags here BEFORE using them. ## Page Thresholds - Create a page when an entity/concept appears in 2+ sources OR is central to one source - Add to existing page when a source mentions something already covered - DON'T create pages for passing mentions - Split a page when it exceeds ~200 lines - Archive fully superseded pages to `_archive/` ## Entity Accounting Gate Every multi-source ingestion must account for named people and organizations before it is complete. 1. Extract every named person or organization that authored a source, owns a case study, coined a central term, or appears in 2+ sources. 2. Record a disposition for each candidate: **Create**, **Update**, or **Skip**. 3. Apply the existing Page Thresholds. A source author is central to that source unless the source is merely quoted in passing. 4. **Create** and **Update** dispositions must be reflected in `entities/`, `index.md`, and `log.md` in the same ingestion batch. 5. **Skip** dispositions must include a one-line reason in the ingestion log or a filed query page. Completion criterion: every qualifying entity candidate is created or updated, and every rejected candidate has an explicit reason. A broad ingestion that produces concepts but no entity dispositions is incomplete. ## Operational Rules (adopted 2026-08-23 from ecosystem analysis) ### 1. Triage before compiling (Astro-Han pattern) After saving the raw file and before editing wiki pages, state the disposition: - **New** — creates one or more new pages - **Update** — merges into existing page(s) - **Disputed** — contradicts existing content (combine with New/Update) - **No material** — adds nothing beyond what the wiki already holds, OR falls under Negative Scope. Keep the raw file, log it as `## [YYYY-MM-DD] ingest | no material: ` and STOP. Do not force a page out of a thin source. ### 2. Status blocks — never silently rewrite history When a newer source supersedes or contradicts an existing claim, keep the old claim for the record and annotate it inline: ```markdown > **Status: Outdated (2026-08)** — superseded by [source]. > **Status: Disputed** — vs ; sources disagree. ``` When the conflicting content lives in separate pages, mark both and cross-link them. ### 3. Grounding invariant Every load-bearing fact (numbers, dates, direct quotes) must exist verbatim in the raw/ files listed in that page's `sources:` frontmatter. Locate it (grep/read) BEFORE writing; write the value exactly as found (`42K`, not `42,000`). Derived values must show their components. Verified mechanically by `wiki/scripts/check_evidence.py` — run during lint. ### 4. Tiered lint authority - **Safe auto-fixes:** index consistency (missing/extra entries), broken relative links with exactly one resolution candidate. - **Mechanical reports (never auto-fix):** `python3 wiki/scripts/check_evidence.py` — grounding-invariant suspects are candidates, not verdicts; judge each against raw context before touching a page. - **Judgment reports (never auto-fix):** contradictions, outdated claims missing Status blocks, orphan pages, missing cross-references, tag-taxonomy violations. Report; let the human decide. ## Update Policy 1. Newer sources generally supersede older ones (note Matt's public take-corrections) 2. Genuinely contradictory: note both positions with dates and sources 3. Mark in frontmatter: `contradictions: [page-name]` 4. Flag for user review in the lint report