AGENTS.md git:20260626.d3457d2A

Immutable. This exact content is served forever at /api/v1/blob/9d939493e723db1f.

# LLM Wiki Newsroom — Schema & Workflow Instructions

> **⚠️ LEGACY COMPATIBILITY MODE — read this first.**
> This file describes the original "no scripts" workflow and has drifted from the
> current architecture. The source of truth is **CLAUDE.md + `.claude/`** (5-role
> multi-agent flow, 9 slash commands, deterministic `tools/` pipeline). Even in
> this minimal mode, four rules are non-negotiable:
> 1. Never hand-edit generated artifacts: `wiki/index.md`, `wiki/sources/_catalog*.md`,
>    any `<!-- AUTO:* BEGIN/END -->` region, or anything under `graph/` —
>    run `python tools/build.py` instead.
> 2. Never hand-write `graph/graph.html` or `graph/*.json` — the HTML is a committed
>    Sigma.js shell that fetches build artifacts.
> 3. Run `python tools/lint.py` and require exit 0 before treating content as published.
> 4. English TitleCase filenames are the default; non-Latin-script entities may use a
>    native-script filename (e.g. `신한은행.md`) — `.claude/policies/naming.md`;
>    new person stubs need ≥3 distinct citing sources + operator approval.

This repo can be driven conversationally by any coding agent, but the deterministic `tools/` scripts (stdlib + a few pip deps, **no API key**) are required for build/lint — they are not optional.

## How to Use

Describe what you want in plain English:
- *"Ingest this file: raw/papers/my-paper.md"*
- *"What does the wiki say about transformer models?"*
- *"Check the wiki for orphan pages and contradictions"*
- *"Build the knowledge graph"*

Or use shorthand triggers:
- `ingest <file>` → runs the Ingest Workflow
- `query: <question>` → runs the Query Workflow
- `lint` → runs the Lint Workflow
- `build graph` → runs the Graph Workflow

---

## Directory Layout

```
raw/          # Immutable source documents — never modify these
wiki/         # Agent owns this layer entirely
  index.md    # Catalog of all pages — generated by `python tools/build.py index`
  overview.md # Living synthesis across all sources
  sources/    # One summary page per source document
  entities/   # People, companies, projects, products
  concepts/   # Ideas, frameworks, methods, theories
  overviews/  # L2-3 cluster landscape overviews
  contradictions/ # L2-3 conflict-axis theme pages
  syntheses/  # Saved query answers
  timelines/  # Chronological hub pages
  trails/     # Associative trails (Memex)
graph/        # Auto-generated graph data (build.py output — do not hand-edit)
tools/        # Optional standalone Python scripts (no API key required)
log.md        # Append-only chronological record (repo root, not under wiki/)
```

---

## Page Format

Every wiki page uses this frontmatter:

```yaml
---
title: "Page Title"
type: source | entity | concept | synthesis | trail | timeline | overview | contradiction
tags: []
sources: []       # list of source slugs that inform this page
last_updated: YYYY-MM-DD
---
```

Use `[[PageName]]` wikilinks to link to other wiki pages.

---

## Ingest Workflow

Triggered by: *"ingest <file>"*

Steps (in order):
1. Read the source document fully
2. Read `wiki/index.md` and `wiki/overview.md` for current wiki context
3. Write `wiki/sources/<slug>.md` — use the source page format below
4. Run `python tools/build.py` — regenerates `wiki/index.md`, catalogs,
   graph artifacts, and the `overview.md` AUTO:STATS block (never hand-edit these)
5. Revise the EDITOR-owned prose of `wiki/overview.md` only if warranted —
   keep `<!-- AUTO:* -->` regions untouched
6. Update/create entity pages **only** for entities cited by ≥3 distinct sources
   (person stubs additionally require operator approval — `.claude/policies/naming.md`)
7. Update/create concept pages for key ideas under the same threshold discipline
8. Flag any contradictions with existing wiki content
9. Append to `log.md`: `## [YYYY-MM-DD] ingest | <Title>`

### Source Page Format

```markdown
---
title: "Source Title"
type: source
tags: []
published: YYYY-MM-DD   # publication date (known)
scraped: YYYY-MM-DD     # date collected
source_file: raw/...
---

## Summary
2–4 sentence summary.

## Key Claims
- Claim 1
- Claim 2

## Key Quotes
> "Quote here" — context

## Connections
- [[EntityName]] — how they relate
- [[ConceptName]] — how it connects

## Contradictions
- Contradicts [[OtherPage]] on: ...
```

---

## Query Workflow

Triggered by: *"query: <question>"*

Steps:
1. Read `wiki/index.md` to identify relevant pages
2. Read those pages
3. Synthesize an answer with inline citations as `[[PageName]]` wikilinks
4. Ask the user if they want the answer filed as `wiki/syntheses/<slug>.md`

---

## Lint Workflow

Triggered by: *"lint"*

Run `python tools/lint.py` (9 deterministic groups; exit 0 is the publication
gate — manual inspection supplements it, never replaces it). Then check for:
- **Orphan pages** — wiki pages with no inbound `[[links]]` from other pages
- **Broken links** — `[[WikiLinks]]` pointing to pages that don't exist
- **Contradictions** — claims that conflict across pages
- **Stale summaries** — pages not updated after newer sources
- **Missing entity pages** — entities mentioned in 3+ pages but lacking their own page
- **Data gaps** — questions the wiki can't answer; suggest new sources

Output a lint report and ask if the user wants it saved to `lint-report.md`.

---

## Graph Workflow

Triggered by: *"build graph"*

Run `python tools/build.py graph` (or `python tools/build.py` for the full
5-phase pipeline). There is **no manual fallback** — `graph/graph.html` is a
committed Sigma.js shell and `graph/*.json` are deterministic build artifacts;
writing them by hand corrupts the visualization and every downstream lint.

---

## Naming Conventions

- Source slugs: `kebab-case` matching source filename
- Entity/concept pages: `TitleCase.md` (e.g. `OpenAI.md`, `RAG.md`) — the default
- Non-Latin-script entities may use a native-script filename (e.g. `신한은행.md`)
  when the name has no standard Latin form (`.claude/policies/naming.md`)

## Index Format

Generated by `python tools/build.py index` — shown for reading reference only; never hand-edit.

```markdown
# Wiki Index

## Overview
- [Overview](overview.md) — living synthesis

## Sources
- [Source Title](sources/slug.md) — one-line summary

## Entities
- [Entity Name](entities/EntityName.md) — one-line description

## Concepts
- [Concept Name](concepts/ConceptName.md) — one-line description

## Syntheses
- [Analysis Title](syntheses/slug.md) — what question it answers
```

## Log Format

`## [YYYY-MM-DD] <operation> | <title>`

Operations: `ingest`, `query`, `lint`, `graph`