From 36183995a7aa911cf61d4a8541a89bc67a922152 Mon Sep 17 00:00:00 2001 From: "Hermes Agent (wiki profile)" Date: Fri, 18 Sep 2026 11:38:56 +0100 Subject: [PATCH] =?UTF-8?q?README.md:=20activation=20guide=20for=20write?= =?UTF-8?q?=20agent=20(profile=20wiki)=20=E2=80=94=20CLI,=20lint,=20ingest?= =?UTF-8?q?,=20isolation=20notes,=20verified=20links?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3c80c75 --- /dev/null +++ b/README.md @@ -0,0 +1,95 @@ +# 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`