Syntology Docs

Contributor reading order

This repo is vibe-coded and standards-gated. Read small, current, normative files first. Huge chronological logs last.

Start here (every session)

  1. CLAUDE.md — 30 lines: STANDARDS → USAGE → QC; shared modules; exit-code contract; never stamp-less derived files; never Bedrock outside bedrock_client.py; never bulk-write without WriteLedger + --intent.
  2. STANDARDS.md — R1–R10 (each rule is a scar).
  3. USAGE.md — copy-paste recipes (syntology doctor / qc on trees that have the package).
  4. QC_PROCESS.md — executable checks and ratchet history.

Then git log --oneline -10 && git status before editing.

Understand the system

  1. These Pages — Home → Architecture → the subsystem you are touching → File catalog.
  2. ARCHITECTURE.md — full review (2026-09-01). Present on fresher local main; may be absent on older origin/main. Prefer it over README §Status when both exist.
  3. REVIEW_FINDINGS.md — defects and SPOFs with IDs.
  4. UPGRADE_CANDIDATE.md — syntology/ kernel and promotion protocol.

Product / pipeline narrative

  1. README.md — what the three runtimes are; Worker/module table. The long Status section drifts (F-12): Phase 2 “not yet loaded” was already false after 2026-08-27 on the live tree. Cross-check.
  2. public/llms.txt — what is actually live for agents vs illustrative pages.
  3. BLUEPRINT.md / WHITEPAPER.md / V1_SHIP_SPEC.md — intent, not always current implementation.
  4. PROJECT_FACTS.md — topic-organized durable facts (better than grepping the log).
  5. CURRENT_STATUS.md — chronological session log (hundreds of KB). Header dates lag. Use for archaeology, not as the source of truth.

Security / ops when relevant

  • SECURITY_INCIDENT_2026-08-21.md before touching Neo4j credentials, /mcp, or GROBID cloud.
  • PR_RETIREMENT.md / ACTIVE_WORK.md on trees that have them (corpus location; do-not-disturb jobs).
  • CLAIMS.md — claims + the command that checks each (when present).

Which root docs to trust when they disagree

QuestionTrust firstDistrust / caveat
Engineering rulesSTANDARDS + QC_PROCESSREADME anecdotes
How to run a checkUSAGE + syntology qcStale copy-paste without ratchet flags
How it is builtARCHITECTURE + this siteCURRENT_STATUS header date
Known holesREVIEW_FINDINGS + SECURITY incidentChat memory
What agents can callpublic/llms.txt + /developersDemo page copy
Ingest chain06_process_new_papers.py source (+ syntology.stages if present)pipeline_stages.py, stage numbers ≥07
Production serving entryDockerfile.api CMD main:appCandidate factory until promoted
Live graph sizepython -m syntology census / pulse APIAny markdown table

Local main vs origin/main

This GitHub Pages branch is cut from origin/main. The operator’s local main may be hundreds of commits ahead with WIP that must not be committed here. If a file cited above is missing on this branch, look it up in the live checkout for research, then land a docs refresh PR later — do not copy pipeline WIP into docs/.