Style Guide

Audience: humans writing pages + agents generating pages. Apply mechanically.

Page types (6)

Use _templates/<type>.md in Obsidian (Cmd+T) to insert the right skeleton.

Frontmatter schema

Required on every page:

---
type: supplier | person | decision | project | meeting | concept
namespace: chanya | venice | six-degrees | alby | goldroom | adg | ahg | shared
title: "Human-readable title with no special chars"
status: draft | active | archived
created: 2026-04-19
updated: 2026-04-19
authors: [kom]                      # or agent name: agent-market-researcher
---

Strongly recommended:

sources:                             # provenance — at least one citation per factual claim
  - type: meetgeek
    id: meeting-abc123
    date: 2026-04-15
  - type: gmail
    id: thread-xyz789
    from: supplier@example.com
    date: 2026-04-12
  - type: file
    path: /Procurement/chanya/invoices/2026/chiang-mai-042.pdf
    ocr_confidence: 0.94
    extracted_at: 2026-04-18T10:22:00Z
  - type: url
    url: https://supplier.example.com/about
    fetched: 2026-04-10
  - type: wiki
    ref: [[chanya/suppliers/chiang-mai-spices]]     # internal citation

tags: [thai, supplier, dry-goods]
last_reviewed: 2026-04-19              # triggers staleness lint if >180 days
review_owner: kom                      # who owns quality
confidence: high | medium | low        # author's own confidence
---

Page body structure

Every page follows the same 4-section rhythm:

# Title

## Context
Why this page exists. 1–3 sentences. What did we want to know?

## Detail
The actual knowledge. Facts, not opinions.
Bullet lists > paragraphs for scan-ability.
Every fact has a citation (inline `[^1]` or frontmatter `sources[]`).

## Actions
What do we do with this knowledge? Open loops, decisions to make, next steps.

## Provenance
Auto-rendered from `sources[]` frontmatter by Dataview. Do not hand-edit unless adding a source mid-page.

Never write a page without Context + Actions. A page with only Detail is a dump, not knowledge. Agents especially tend to skip these — enforce in review.

Naming conventions

• Filenames: lowercase, kebab-case, no spaces: chiang-mai-spices.md
• Dates in filenames: ISO YYYY-MM-DD- prefix for decision + meeting
• Titles in frontmatter: capitalized, human-readable: "Chiang Mai Spices Pty Ltd"
• Slugs: <60 characters. If longer, it's probably 2 pages.

Tagging

• Use tags: frontmatter (array), not inline #tag
• Lowercase, kebab-case
• Reuse existing tags — grep before inventing. grep -rh "^ - " **/*.md | sort -u

Linking

• Internal: [[chanya/suppliers/chiang-mai-spices]] — full path, no brackets/extension
• External: standard Markdown [text](https://...)
• Procurement raw docs: [[../../Procurement/chanya/invoices/2026/foo.pdf]] — but better practice is to cite via sources[] frontmatter, not inline

What agents must do (enforced in MCP bridge)

When an agent writes a page:

1. ✅ Full frontmatter (every required field)
2. ✅ At least one source cited
3. ✅ All 4 body sections present (Context / Detail / Actions / Provenance)
4. ✅ authors[] includes the agent's name
5. ✅ updated: reflects today
6. ❌ No fabricated facts without confidence: low flag
7. ❌ No editing of existing decision type pages — create a new decision page superseding

Violations → reject at MCP bridge; agent must retry.

What humans may do that agents may not

• Edit a decision without superseding (you know the context)
• Write pages with sources: [] for personal notes (agents require citations)
• Delete pages outright (agents can only archive: status: archived)

Lint rules (enforced by T12 lint worker — future)

• Orphan page (no backlinks after 30 days) → flag
• Stale page (last_reviewed > 180 days, status: active) → flag
• Missing required frontmatter → reject
• Two pages assert contradictory facts → flag, require human resolution
• Agent-written page with no sources[] → reject

Naming examples

Diagrams — use Mermaid, never ASCII art (added 2026-06-07)

Author diagrams as fenced `mermaid blocks inside the markdown. One diagram then renders in THREE places with zero extra work: Obsidian preview, GitLab, and the generated HTML docs.

​```mermaid
graph TD
  A["Source"] --> B["KO vault"]
  B --> C["Consumer"]
  classDef ko fill:#715EE3,color:#fff,stroke:#291F50;
  class B ko;
​```

• Every project page should carry an ## Architecture Mermaid diagram (data flow / dependencies, grounded in the page's actual content).
• Style the Knowledge-OS / source-of-truth node with fill:#715EE3 (Aspire purple) so it's visually distinct.
• Do NOT paste ASCII box-art — it doesn't render and can't be linted.

HTML docs — markdown is source, HTML is the human read-surface (added 2026-06-07)

The vault stays markdown (Obsidian, lint, FTS, and LLM-ingest are all markdown-native). For humans who want to grok a project fast, generate a static HTML site:

cd ~/Desktop/Claude/projects/knowledge-os
python3 scripts/build_html_docs.py     # → docs-html/index.html

• Output is a build artifact (docs-html/, gitignored) — never edit HTML by hand.
• The generator renders Mermaid, a Domain × Type category index, and an auto-generated per-page "Relationships" diagram from [[wikilinks]].
• Published for the team via GitLab Pages (.gitlab-ci.yml in the vault repo).

Ingesting raw data → a vault page (added 2026-06-07)

Pick the method by data shape:

One-command helper for the first two tiers:

cd ~/Desktop/Claude/projects/knowledge-os
python3 scripts/ingest_raw.py <file-or-url> --namespace goldroom --type concept [--commit]

It fetches the source, LLM-synthesises a structured page via the Aspire LLM Gateway, writes it lint-clean with sources[] set to the origin, and (with --commit) pushes it. Review before committing.

When unsure

Ask kom (vault owner). Or write in _inbox/ first with status: draft and let a human promote it.