ATOCore/docs/plans/wiki-reorg-plan.md

Wiki Reorg Plan — Human-Readable Navigation of AtoCore State

SUPERSEDED — 2026-04-22. Do not implement this plan. It has been replaced by the read-only operator orientation work at docs/plans/operator-orientation-plan.md (in the ATOCore-clean workspace). The successor reframes the problem as orientation over existing APIs and docs rather than a new /wiki surface, and drops interaction browser / memory index / project-page restructure from scope. Nothing below should be picked up as a work item. Kept in tree for context only.

Date: 2026-04-22 Author: Claude (after walking the live wiki at http://dalidou:8100/wiki and reading src/atocore/engineering/wiki.py + /wiki/* routes in src/atocore/api/routes.py) Status: SUPERSEDED (see banner above). Previously: Draft, pending Codex review Scope boundary: This plan does NOT touch Inbox / Global / Emerging. Those three surfaces stay exactly as they are today — the registration flow and scope semantics around them are load-bearing and out of scope for this reorg.

---

Position

The wiki is Layer 3 of the engineering architecture (Human Mirror — see docs/architecture/engineering-knowledge-hybrid-architecture.md). It is a derived view over the same database the LLM reads via atocore_context / atocore_search. There is no parallel store; if a fact is in the DB it is reachable from the wiki.

The user-facing problem is not representation, it is findability and structure. Content the operator produced (proposals, decisions, constraints, captured conversations) is in the DB but is not reachable along a natural human reading path. Today the only routes to it are:

• typing the right keyword into /wiki/search
• remembering which project it lived under and scrolling the auto- generated mirror markdown on /wiki/projects/{id}
• the homepage "What the brain is doing" strip, which shows counts of audit actions but no content

There is no "recent conversations" view, no memory index, no way to browse by memory type (decision vs preference vs episodic), and the topnav only exposes Home / Activity / Triage / Dashboard.

Goal

Make the wiki a surface the operator actually uses to answer three recurring questions:

1. "Where did I say / decide / propose X?" — find a memory or interaction by topic, not by exact-string search.
2. "What is the current state of project Y?" — read decisions, constraints, and open questions as distinct sections, not as one wall of auto-generated markdown.
3. "What happened in the system recently, and what does it mean?" — a human-meaningful recent feed (captures, promotions, decisions recorded), not a count of audit-action names.

Success criterion: for each of the three questions above, a first-time visitor reaches a useful answer in ≤ 2 clicks from /wiki.

Non-goals

• No schema changes. All data already exists.
• No change to ingestion, extraction, promotion, or the trust rules.
• No change to Inbox / Global / Emerging surfaces or semantics.
• No change to /admin/triage or /admin/dashboard.
• No change to the atocore_context / atocore_search LLM-facing APIs.
• No new storage. Every new page is a new render function over existing service-layer calls.

What it will do

Five additions, in priority order. Each is independently mergeable and independently revertable.

W-1 — Interaction browser: /wiki/interactions

The DB holds 234 captured interactions (per ledger 2026-04-22). None are readable in the wiki. Add a paginated list view and a detail view.

• /wiki/interactions?project=&client=&since= — list, newest first, showing timestamp, client (claude-code / openclaw / test), inferred project, and the first ~160 chars of the user prompt.
• /wiki/interactions/{id} — full prompt + response, plus any candidate / active memories extracted from it (back-link from the memory → interaction relation if present, else a "no extractions" note).
• Filters: project (multi), client, date range, "has extractions" boolean.

Answers Q1 ("where did I say X") by giving the user a time-ordered stream of their own conversations, not just extracted summaries.

W-2 — Memory index: /wiki/memories

Today /wiki/memories/{id} exists but there is no list view. Add one.

• /wiki/memories?project=&type=&status=&tag= — filterable list. Status defaults to active. Types: decision, preference, episodic, knowledge, identity, adaptation.
• Faceted counts in the sidebar (e.g. "decision: 14 · preference: 7").
• Each row links to /wiki/memories/{id} and, where present, the originating interaction.

W-3 — Project page restructure (tabbed, not flat)

/wiki/projects/{id} today renders the full mirror markdown in one scroll. Restructure to tabs (or anchored sections, same thing semantically) over the data already produced by generate_project_overview:

• Overview — stage, client, type, description, headline state.
• Decisions — memories of type decision for this project.
• Constraints — project_state entries in the constraints category.
• Proposals — memories tagged proposal or type preference with proposal semantics (exact filter TBD during W-3; see Open Questions).
• Entities — current list, already rendered inline today.
• Memories — all memories, reusing the W-2 list component filtered to this project.
• Timeline — interactions for this project, reusing W-1 filtered to this project.

No new data is produced; this is purely a slicing change.

W-4 — Recent feed on homepage

Replace the current "What the brain is doing" strip (which shows audit action counts) with a content feed: the last N events that a human cares about —

• new active memory (not candidate)
• memory promoted candidate → active
• state entry added / changed
• new registered project
• interaction captured (optional, may be noisy — gate behind a toggle)

Each feed row links to the thing it describes. The audit-count strip can move to /wiki/activity where the full audit timeline already lives.

W-5 — Topnav exposure

Surface the new pages in the topnav so they are discoverable:

Current: 🏠 Home · 📡 Activity · 🔀 Triage · 📊 Dashboard Proposed: 🏠 Home · 💬 Interactions · 🧠 Memories · 📡 Activity · 🔀 Triage · 📊 Dashboard

Domain pages (/wiki/domains/{tag}) stay reachable via tag chips on memory rows, as today — no new topnav entry for them.

Outcome

• Every captured interaction is readable in the wiki, with a clear path from interaction → extracted memories and back.
• Memories are browsable without knowing a keyword in advance.
• A project page separates decisions, constraints, and proposals instead of interleaving them in auto-generated markdown.
• The homepage tells the operator what content is new, not which audit action counters incremented.
• Nothing in the Inbox / Global / Emerging flow changes.
• Nothing the LLM reads changes.

Non-outcomes (explicitly)

• This plan does not improve retrieval quality. It does not touch the extractor, ranking, or harness.
• This plan does not change what is captured or when.
• This plan does not replace /admin/triage. Candidate review stays there.

Sequencing

1. W-1 first. Interaction browser is the biggest findability win and has no coupling to memory code.
2. W-2 next. Memory index reuses list/filter infra from W-1.
3. W-3 depends on W-2 (reuses the memory list component).
4. W-4 is independent; can land any time after W-1.
5. W-5 lands last so topnav only exposes pages that exist.

Each step ships with at least one render test (HTML contains expected anchors / row counts against a seeded fixture), following the pattern already in tests/engineering/ for existing wiki renders.

Risk & reversibility

• All additions are new routes / new render functions. Reverting any step is a file delete + a topnav edit.
• Project page restructure (W-3) is the only edit to an existing surface. Keep the flat-markdown render behind a query flag (?layout=flat) for one release so regressions are observable.
• No DB migrations. No service-layer signatures change.

Open questions for Codex

1. "Proposal" as a first-class filter (W-3) — is this a memory type, a domain tag, a structural field we should add, or should it stay derived by filter? Current DB has no explicit proposal type; we'd be inferring from tags/content. If that inference is unreliable, W-3's Proposals tab becomes noise.
2. Interaction → memory back-link (W-1) — does the current schema already record which interaction an extracted memory came from? If not, is exposing that link in the wiki worth a schema addition, or should W-1 ship without it?
3. Recent feed noise floor (W-4) — should every captured interaction appear in the feed, or only interactions that produced at least one candidate memory? The former is complete but may drown out signal at current capture rates (~10/day).
4. Ordering vs V1 Completion track — should any of this land before V1-A (currently gated on soak ~2026-04-26 + density 100+), or is it strictly after V1 closes?

Workspace note

Canonical dev workspace is C:\Users\antoi\ATOCore (per CLAUDE.md). Any Codex audit of this plan should sync from origin/main at or after 2712c5d before reviewing.