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.