julian
22b1b069df
Initialize CLAUDE.md schema, index, and log; ingest three architecture sources (system overview, Teltonika ingestion design, official Teltonika data-sending protocols) into 7 entity pages, 8 concept pages, and 3 source pages with wikilink cross-references.
116 lines
5.0 KiB
Markdown
116 lines
5.0 KiB
Markdown
# TRM Wiki — Schema & Conventions
|
||
|
||
This repo is an LLM-maintained wiki. The human curates sources and asks questions. You (the LLM) own all wiki pages: you write them, update them, and keep them consistent.
|
||
|
||
## Layout
|
||
|
||
```
|
||
docs/
|
||
├── CLAUDE.md # this file — schema and workflows
|
||
├── index.md # content catalog (you maintain)
|
||
├── log.md # chronological activity log (you append to)
|
||
├── raw/ # immutable source documents — READ ONLY
|
||
└── wiki/ # all LLM-generated pages live here
|
||
├── sources/ # one page per ingested source
|
||
├── entities/ # people, orgs, products, places
|
||
├── concepts/ # ideas, topics, themes
|
||
└── synthesis/ # comparisons, analyses, overview pages
|
||
```
|
||
|
||
Rules:
|
||
- **Never modify anything in `raw/`.** Treat it as immutable source of truth.
|
||
- **Never edit the wiki by hand is the user's expectation** — but the user may occasionally. If you see human edits, respect them.
|
||
- All wiki pages are markdown with YAML frontmatter (see below).
|
||
- Use Obsidian-style `[[wikilinks]]` for cross-references between wiki pages. Use standard markdown links for external URLs and for links into `raw/`.
|
||
|
||
## Page frontmatter
|
||
|
||
Every page in `wiki/` starts with frontmatter:
|
||
|
||
```yaml
|
||
---
|
||
title: <page title>
|
||
type: source | entity | concept | synthesis
|
||
created: YYYY-MM-DD
|
||
updated: YYYY-MM-DD
|
||
sources: [<source-page-name>, ...] # which sources contribute to this page
|
||
tags: [<tag>, ...]
|
||
---
|
||
```
|
||
|
||
For `type: source` pages, also include:
|
||
```yaml
|
||
source_path: raw/<filename>
|
||
source_date: YYYY-MM-DD # date of the original document, if known
|
||
source_kind: article | paper | transcript | note | image | other
|
||
```
|
||
|
||
## Workflows
|
||
|
||
### Ingest (when user says "ingest X" or drops a new file in raw/)
|
||
|
||
1. Read the source from `raw/`.
|
||
2. Briefly discuss key takeaways with the user before writing — confirm what to emphasize.
|
||
3. Create `wiki/sources/<slug>.md` with:
|
||
- Frontmatter (type: source).
|
||
- One-paragraph TL;DR.
|
||
- Key claims / facts as a bulleted list, each with enough context to stand alone.
|
||
- Notable quotes (verbatim, with location if available).
|
||
- Open questions or things to follow up on.
|
||
4. For each entity or concept the source touches:
|
||
- If a page exists in `wiki/entities/` or `wiki/concepts/`, update it: add new facts, link the new source in `sources:` frontmatter, flag contradictions with existing claims explicitly (don't silently overwrite).
|
||
- If no page exists and the entity/concept is substantive, create one.
|
||
5. Update `index.md` — add the new source row and any new entity/concept rows.
|
||
6. Append an entry to `log.md`.
|
||
|
||
A single ingest typically touches 5–15 wiki files. That's expected.
|
||
|
||
### Query (when user asks a question)
|
||
|
||
1. Read `index.md` first to locate relevant pages.
|
||
2. Read those pages (and follow wikilinks as needed).
|
||
3. Answer with citations: link `[[page-name]]` for wiki pages, and reference the underlying source pages so the user can trace claims back to `raw/`.
|
||
4. If the answer is substantive (a comparison, an analysis, a new connection), offer to file it into `wiki/synthesis/` as a new page. Don't file by default — ask first.
|
||
5. If the wiki can't answer the question, say so plainly. Suggest what source would fill the gap.
|
||
|
||
### Lint (when user says "lint" or "health-check")
|
||
|
||
Scan the wiki for:
|
||
- Contradictions between pages (same claim, different values).
|
||
- Stale claims newer sources have superseded.
|
||
- Orphan pages (no inbound wikilinks).
|
||
- Concepts mentioned in 3+ pages but lacking their own page.
|
||
- Missing cross-references (entity X mentioned on page Y but not linked).
|
||
- Frontmatter drift (missing fields, wrong types).
|
||
|
||
Report findings as a checklist. Don't fix automatically — confirm with the user first.
|
||
|
||
## Log format
|
||
|
||
`log.md` is append-only. Each entry starts with a header line in this exact format so it's grep-able:
|
||
|
||
```
|
||
## [YYYY-MM-DD] <op> | <short title>
|
||
```
|
||
|
||
Where `<op>` is one of: `ingest`, `query`, `lint`, `synthesis`, `note`. Body underneath is 1–5 lines: what happened, what files changed.
|
||
|
||
Example:
|
||
```
|
||
## [2026-04-30] ingest | Acme Q1 earnings call transcript
|
||
|
||
Created wiki/sources/acme-q1-earnings.md. Updated [[Acme]], [[revenue-recognition]].
|
||
Flagged contradiction with [[acme-2025-guidance]] re: margin outlook.
|
||
```
|
||
|
||
## Index format
|
||
|
||
`index.md` is a content catalog organized by section: Sources, Entities, Concepts, Synthesis. Each row: `- [[page-name]] — one-line summary`. Keep summaries tight. Re-sort alphabetically within each section after edits.
|
||
|
||
## Style
|
||
|
||
- Wiki pages should be readable on their own. Don't write "as discussed above" — there's no above for someone landing via search.
|
||
- Prefer short, declarative sentences over hedged prose. Where uncertainty matters, say so explicitly with a `> note:` callout.
|
||
- Quote sparingly and verbatim. Paraphrase by default.
|
||
- When new information conflicts with an existing page, do not silently overwrite. Add the new claim, mark the conflict, and let the user adjudicate.
|