Wiki

What it does

Wiki stores durable, searchable Markdown knowledge pages for operational knowledge, project context, policies, decisions, and reusable internal notes. Each page has a stable topic_key that does not change when its human-facing slug changes, an immutable revision history, explicit manual/generated provenance, and exact assertion/evidence references where generated content is involved. Pages are archived instead of hard-deleted.

Autonomous generated content is a publication input, not an automatic page overwrite. Background agents, Memory Dreaming, and imports create a change proposal in draft; an authorized human can approve or reject it, and an approved proposal is published atomically as a new immutable page revision. A manually authored or manually edited page is protected from background generated writes.

How to open it

• Web: /modules/wiki. Wiki is a fixed bundled module ("fixed": true in bundled-modules/wiki/module.json): it is always active, is not installed into the workspace copy, and cannot be deactivated or removed from Module Store.
• React renderer: src/components/modules/wiki-module.tsx.
• Apple client: the Wiki is a native screen in the Clapilot Apple app (iOS/macOS), reachable from the Content area of the side menu (clients/apple/ClapilotApple/Sources/Clapilot/Views/WikiView.swift).

Key workflows

Find and read pages

1. Search by title, summary, Markdown content, or tags.
2. Open a page to see its generated/manual badge, source and evidence freshness, rendered GitHub-flavored Markdown, and the summary as a rounded TL;DR callout above the body.
3. Pages with multiple headings include a linked table of contents.
4. Preview rendering allows a sanitized subset of inline HTML (for example <u>, <mark>, <sub>, <sup>, <ins>, <del>, <kbd>, <abbr>), so scripts in agent- or import-authored pages cannot run.

Create and edit pages

1. Create a Markdown page, then edit title, slug, tags, and the Markdown body.
2. Edit the page summary in the TL;DR callout in Edit mode; it renders above the body in Preview.
3. Format with the Markdown toolbar (headings, bold, italic, underline, strikethrough, inline code, bulleted/numbered lists, quote, code block, link), including Cmd/Ctrl+B/I/U/K shortcuts.
4. Switch between editing and rendered output with the icon-only Edit/Preview segmented control.
5. Every save creates a new immutable revision. An authorized reviewer can restore an older revision; restore creates another revision and never mutates history.

Review generated proposals

1. Open the global Review queue for proposals to new or existing pages, or open Proposals on a page to inspect only its pending generated changes. Each entry shows summary, source, exact assertion/evidence counts, and evidence check time.
2. An admin can approve or reject a draft. Approval does not change the live page.
3. Publishing an approved proposal performs the page write, immutable revision insert, and proposal state change in one database transaction. Publication is rejected if the page changed since the proposal was based on it.
4. Exact-content and high-overlap semantic guards reject duplicate pages and duplicate open proposals. Slug similarity alone is not treated as topic identity. Web writes, native Dreaming proposals, and migration backfills all use the deterministic wiki-semantic-v1 signature (title, summary, and H1-H3 headings after explicit accent folding and stop-word removal) with a Jaccard duplicate threshold of 0.78.

Archive pages

Pages are archived instead of hard-deleted: the DELETE /api/wiki/pages/:id endpoint sets status='archived'.

Apple client

The native screen provides the core searchable page list, full-screen Markdown editor, rendered GFM preview, create, and archive workflows through /api/wiki/pages. Proposal review, provenance detail, revision history, and revert are currently surfaced in the web Wiki; the shared API contracts are available for a later native UI pass. Both clients publish the same live page context so chat and Live Voice agents can act on the open page.

How the agent can drive it

The module publishes page context (activeWikiPageId, activeWikiPageSlug, activeWikiPageTitle, wikiSearch) so agents can update the current page when the user refers to "this page".

The native runtime, Live Voice, and Clapilot CLI expose the same Wiki tool family:

• wiki_search
• wiki_get_page
• wiki_upsert_page — the authenticated user-directed write path; it accepts markdown_content for the full Markdown body, optional summary, tags, source_refs, metadata, and update_active=true. Chat and Live Voice dispatch it with source_type=manual and metadata.userDirected=true, so the result is a protected manual revision. Autonomous/background producers, including Dreaming, use proposals instead.
• wiki_archive_page

For broad "fill the Wiki from everything we know" requests, the native runtime should start with context_search using depth=deep or intent=wiki_synthesis, then call context_get on relevant hits (including wiki:<id-or-slug> source-qualified ids) before writing. That unified pass checks approved Learning objects, existing Wiki pages, native memory, session history/summaries, and the Knowledge Graph together.

Configuration & limits

HTTP API (used by web and Apple clients):

Storage — the original page table is introduced by migration 173_wiki_pages.sql; publication v2 is added by 194_wiki_publication_v2.sql, and the reversible semantic-contract backfill is migration 196_wiki_semantic_signature_v1.sql:

• slug is unique and normalized to kebab-case (enforced by a check constraint).
• topic_key is the stable machine identity and is independent of the mutable slug.
• markdown_content is the authoritative page body.
• summary and tags are optimized for search and agent selection.
• content_origin and manual_protected make content ownership explicit. source_type retains the more specific manual, agent, dream, or imported producer.
• source_refs, assertion_refs, and evidence_refs contain exact { kind, id, ... } references; evidence_checked_at records freshness.
• wiki_page_revisions is append-only. Database triggers reject revision updates and deletes.
• wiki_change_proposals retains the full proposed snapshot and the draft -> approved|rejected -> published review trail.
• semantic_signature_version identifies the derivation contract. Version wiki-semantic-v1 is shared by src/lib/wiki.ts, the native Wiki proposal publisher, and the SQL backfill. Runtime writes take a versioned semantic advisory lock before duplicate checks, and the backfill preserves every prior derived value in wiki_semantic_signature_migration_audit; restore_wiki_semantic_signature_v1() restores those values without deleting page or revision history.
• status is active or archived.
• Clearly identified legacy fallback pages (metadata.synthesizedFromMemories, fallback metadata, or legacy fallback tags) are archived by migration with archive_reason='legacy_generated_fallback'; their migration snapshot remains in revision history.

Dreaming integration

Memory Dreaming v2 may return Wiki candidates alongside canonical assertions, but it must not update wiki_pages directly. A candidate is submitted through createWikiChangeProposal (or POST /api/wiki/proposals) with a stable topic_key, exact assertion references, exact supporting evidence references, and source memory/dream references. It remains a draft until review. Approval rejects private, terminal, conflicted, unresolved-conflict, or evidence-pending assertions; a review that promotes a candidate assertion also schedules its projection on that assertion's actual instance outbox.

The publication foundation is deliberately separate from memory selection and consolidation. src/lib/wiki.ts exposes proposal, review, atomic publish, revision, and revert helpers so the native runtime can use the same invariants without coupling Wiki identity to a memory filename, a slug, or a Knowledge Graph display node.

The former deterministic "guarantee a page" fallback is not a publication path. Previously synthesized fallback pages are explicitly archived and marked during migration rather than being silently treated as reviewed knowledge.