# Personal LLM Wiki — Activation & Usage Guide

Repo: `https://gitea.maukit.com/hermes/personal-wiki`
Local clone: `/opt/data/wiki`
Isolated agent profile: `/opt/data/profiles/wiki/`
Profile `.env`: `/opt/data/profiles/wiki/.env` (`WIKI_PATH=/opt/data/wiki`)

## Activating the Write Agent (Wiki Profile)

The only agent allowed to write to `/opt/data/wiki` is the isolated `wiki` Hermes profile.

### Direct CLI activation
```bash
# Run the wiki agent interactively (isolated session, isolated memory/skills/state)
/opt/hermes/bin/hermes --profile wiki

# One-shot ingestion: provide source, agent writes updates and pushes
/opt/hermes/bin/hermes --profile wiki chat -q \
  "Ingest /path/to/article.md into wiki. Update index, log, SCHEMA-consistent pages, and push."

# One-shot lint / check
/opt/hermes/bin/hermes --profile wiki chat -q \
  "Run full lint (SCHEMA.md §3): orphan pages, broken wikilinks, contradictions, stale content, source drift, tag audit. Push results to queries/ or log.md."

# Worktree mode (prevents git conflicts if another agent has the repo open)
/opt/hermes/bin/hermes --profile wiki -w chat -q "Ingest new source and push commit."
```

### Programmatic (from any host/agent)
```bash
# Other agents / hosts can READ via git clone (public repo):
git clone https://gitea.maukit.com/hermes/personal-wiki.git

# Only the wiki profile writes. Other agents should never edit /opt/data/wiki directly.
# If another agent needs to ingest, delegate to the profile:
/opt/hermes/bin/hermes --profile wiki chat -q "Ingest: [description + source path/URL]"
```

### What the agent does on activation (per `SCHEMA.md`)
On every session it must:
1. Read `SCHEMA.md` (domain, conventions, taxonomy, thresholds)
2. Read `index.md` (existing pages, navigation)
3. Read last 30 lines of `log.md` (recent actions, rotation check)
4. Only after orientation: ingest / query / lint / create / archive / push

### Running checks (lint pattern from `SCHEMA.md` §3)
The profile agent supports these lint checks:
- Orphan pages (zero inbound `[[wikilinks]]`)
- Broken wikilinks (links to non-existent files)
- Index completeness (every `.md` page in `index.md`)
- Frontmatter validation (`title`, `created`, `updated`, `type`, `tags`, `sources`)
- Tag audit (tags must exist in taxonomy)
- Stale content (`updated` >90 days before newest source for same entity)
- Contradictions (`contested: true` / `contradictions:` tracking)
- Source drift (`sha256:` on `raw/` files — recompute, flag mismatch)
- Page size (>200 lines → split candidate)
- Log rotation (>500 entries → rotate to `log-YYYY.md`)

To trigger from CLI:
```bash
/opt/hermes/bin/hermes --profile wiki chat -q "Run lint (§3 SCHEMA.md) and append findings to log.md with file paths and severity grouping."
```

### Ingestion workflow (SCHEMA.md §1)
When ingesting a source (file / URL / pasted text):
1. Capture raw source → `raw/articles/`, `raw/papers/`, `raw/transcripts/`, or `raw/assets/`
2. Add raw frontmatter (`source_url`, `ingested`, `sha256` of body after frontmatter)
3. Check existing pages via `search_files` / `read_file` (orient first)
4. Create/update wiki pages (only if meeting Page Thresholds: 2+ mentions or central to 1 source)
5. Add cross-references (`[[wikilinks]]` — min 2 outbound per page)
6. Use only tags from taxonomy; add new tags to `SCHEMA.md` first
7. Set `confidence:` (`high` for multi-source; `medium` / `low` for single / opinion-heavy)
8. Note contradictions (`contested: true`, `contradictions:` list) instead of overwriting
9. Update `index.md` (alphabetically, count, last-updated)
10. Append to `log.md` (date, action, files created/updated)
11. Push: `git add -A && git commit -m "..." && git push origin main`

### Key files (verified in repo, commit `f83351c`)
- `/opt/data/wiki/SCHEMA.md` — conventions, taxonomy, thresholds, update policy
- `/opt/data/wiki/index.md` — navigation, sectioned catalog
- `/opt/data/wiki/log.md` — chronological actions (initialized 2026-09-18)
- `/opt/data/wiki/SETUP.md` — profile + repo info (not in `SCHEMA.md`; added after init)
- `/opt/data/profiles/wiki/.env` — `WIKI_PATH=/opt/data/wiki`
- Skill reference: `/opt/data/skills/research/llm-wiki/SKILL.md` (patched for `/opt/data/wiki` root)

### Security / isolation notes
- Only `wiki` profile writes; other profiles / hosts must not edit `/opt/data/wiki` directly.
- The repo (`gitea.maukit.com/hermes/personal-wiki`) is public; `floof` has push access (verified via Gitea API: user id 3).
- Token (`/opt/data/.secrets/gitea_hermes_token`) is for `gitea.maukit.com` auth; `mcp__gitea__*` requires manual `GITEA_ACCESS_TOKEN` injection (current session requires `WIKI_PATH` only).
- Second Telegram bot: deferred per session notes (`SETUP.md`, `log.md`, session context).

### Related references
- `SCHEMA.md` (§1 Ingest, §2 Query, §3 Lint, §4 Architecture, §5 Pitfalls)
- Skill file: `/opt/data/skills/research/llm-wiki/SKILL.md`
- Repo URL: `https://gitea.maukit.com/hermes/personal-wiki`