---
title: "Admin Wiki"
description: "Postgres Obsidian-like Markdown knowledge vault for admins, buyers, integrators, ring-mcp agents, and product NODUS pages from Store Research"
locale: "en"
---
# Admin Wiki

> **Info**
> Use **Founder** / **Developer** tabs in the docs sidebar to filter this page. Admin Wiki is a **compounding project knowledge base** (Markdown + `[[wikilinks]]`) — not the filesystem `/docs` MDX library and not the news Markdown CMS (NewsRichEditor + shortcodes). Personal member files live in [Ring File Cabinet](/docs/features/file-cabinet.md), not the wiki vault.

Ring clones store **operational knowledge** in a Postgres vault: tenant-wide pages plus optional **project-order** spaces. Humans edit at `/admin/wiki` and on Order Lab desks; agents search and mutate through **ring-mcp** using the same WikiKernel.

| Layer | Where |
|-------|--------|
| UI | `/admin/wiki` · buyer `/my-orders/[id]` · integrator `/my-jobs/[id]` |
| Nav | Admin supermenu **Content & Blog** → Wiki · right rail title + actions |
| Kernel | `features/wiki/**` (`wiki-service.ts`, ACL, wikilinks, search) |
| Collections | `wiki_pages`, `wiki_links`, `wiki_events` |
| Migration | `data/migrations/040_wiki_pages.sql` |
| HTTP | `/api/wiki`, `/api/wiki/[id]` |
| MCP | `/api/mcp/v1/wiki*` · tools `ring-wiki-*` |

```mermaid
flowchart LR
  AdminUI["/admin/wiki"] --> Kernel["WikiService"]
  DeskUI["my-orders / my-jobs"] --> Kernel
  RingMCP["ring-wiki-*"] --> Kernel
  Kernel --> Pages["wiki_pages"]
  Kernel --> Links["wiki_links"]
  Kernel --> Events["wiki_events"]
```

### For founders

## Why this matters for your clone

Chat and tickets forget. A wiki **compiles** what your clone knows about a settler project: brand decisions, deploy notes, integrator handoffs — with links that stay current.

  
- **[Admin console](/docs/features/admin.md)** — Wiki appears in the Admin supermenu under Content & Blog, and in the right rail beside the editor.

  
- **[Owner Project Lab](/docs/features/owner-project-lab.md)** — Each paid project order can open a project vault on buyer and integrator desks.

  
- **[CRM project orders](/docs/features/owner-project-lab.md)** — Jump from Wiki actions to `/admin/crm/orders` when a page belongs to a ringization job.

  
- **[Ring MCP](/docs/development/ring-mcp.md)** — Agents self-build and query the vault without opening the UI.

  
- **[Store Agent Knowledge](/docs/features/store.md)** — Research creates product NODUS wiki pages via createProductNodusWikiFromDraft / wikiCreateAction.

### Typical scenarios

1. **Platform playbook** — Admins keep tenant pages for “how we ringize”, payment rails, and support macros.
2. **Per-order brain** — Buyer and integrator share a `po:{orderId}` vault for that clone’s decisions (no secrets — those stay in Order Lab `#secrets`).
3. **Agent ingest** — ring-mcp creates/updates concept pages, appends ops events, and lints dead `[[wikilinks]]`.
4. **Product NODUS from Store Research** — Vendor/admin **Agent Knowledge → Research** writes a tenant wiki page (`Product NODUS — {name}`) and stores `productNodusWiki` on the product — full NODUS JSON in the vault, markdown brief on the product. See [Multi-Vendor Store](/docs/features/store.md).
5. **Cross-vault cite** — From a project page, link platform concepts with `[[@Payments]]` or `[[tenant:Payments]]`.

### Operator checklist

- Open `/admin/wiki` as platform admin; confirm `_schema` seeded (title lives in the **right rail**).
- Use rail **Actions**: CRM project orders, News, CRM tasks, Wiki docs.
- Create a folder path (e.g. `concepts`) by setting **path** on new pages — folders are path prefixes, not empty docs.
- Use `[[Page]]` for same-vault links; use `[[@Title]]` to cite tenant knowledge from a project vault.
- On `/my-orders/[id]` or `/my-jobs/[id]`, use **Project Wiki** for that order only.
- Never paste Firebase keys or RingBase tokens into wiki bodies.

### Who can write what

| Actor | Tenant vault | Project vault |
|-------|--------------|---------------|
| Admin / Buyer | Full read/write | Full (own orders) |
| Integrator | Read + **append-only** | Full (assigned orders) |
| Agent (ring-mcp) | **Read only** | Full |

### For developers

## Implementation

WikiKernel owns ACL, link graph, search envelope, and events. Adapters are thin: Admin UI, desk panel, HTTP, MCP.

### Domain

- **`vaultKey`**: TypeScript union `tenant` \| `po:{projectOrderId}` — a **page field**, not an env var and not a `ring-config` key.
- **Body SSOT**: `bodyMarkdown` (not the news Markdown CMS) — Admin UI edits via TipTap rich preview with **Source Markdown** toggle; save still persists Markdown. News articles use NewsRichEditor + `[[embed:]]` / `[[mood:]]` / `[[video:]]` shortcodes instead of wiki `[[wikilinks]]`.
- **Wikilink parser**: ignores fenced + inline code (docs examples do not create graph edges).
- **Lint**: `ring-wiki-lint` / Lint vault; **Create stubs** auto-creates draft concept pages for real `missing_page` issues.
- **Graph SSOT**: `wiki_links` edges (`local` \| `tenant_ref`)
- **Catalog**: derived list/search — no maintained `_index.md`
- **Ops log**: `wiki_events` append-only
- **Special page**: tenant `_schema` (agent constitution) seeded on first open; legacy example-link body is one-shot repaired on ensure
- **Tree**: folder tree absorbed from file-registry-viewer (`buildTree` / expand / folder counts / ranked quick search)

`VaultKey` is only a TypeScript type in `features/wiki/types.ts`. Do **not** add `VAULT_KEY` to `.env` or `ring-config.json`. A `'use server'` file must not re-export types or sync helpers — Next treats every export as a server action and type re-exports become runtime `ReferenceError: VaultKey is not defined`. Keep actions in `app/_actions/wiki.ts` as async functions only; import types from `@/features/wiki/types`.

### Wikilinks

| Form | Resolve |
|------|---------|
| `[[slug]]` / `[[Title]]` / `[[path/slug]]` / `[[Page\|display]]` | Same vault |
| `[[@Payments]]` / `[[tenant:Payments]]` | Tenant vault |

### Module map

| Concern | Path |
|---------|------|
| Types / ACL / parser / search | `features/wiki/types.ts`, `acl.ts`, `wikilink-parser.ts`, `search-score.ts` |
| Service | `features/wiki/wiki-service.ts` |
| Actor resolve (buyer/integrator) | `features/wiki/resolve-wiki-actor.ts` |
| Admin workspace | `features/wiki/components/wiki-workspace.tsx` |
| Desk panel | `features/wiki/components/wiki-desk-panel.tsx` |
| Server actions | `app/_actions/wiki.ts` (async exports only) |
| Right rail | `admin-nav-config` rail section `wiki` + `admin-rail.tsx` |
| MCP routes | `app/api/mcp/v1/wiki/**` |
| BackendSelector | `wiki_pages`, `wiki_links`, `wiki_events` |

### ring-mcp tools

| Tool | Role |
|------|------|
| `ring-wiki-search` | Legiox-shaped `matches[]` (lexical) |
| `ring-wiki-list` / `get` | Catalog + backlinks |
| `ring-wiki-create` / `update` / `delete` | CRUD (`confirm` on delete); agent tenant create/write denied |
| `ring-wiki-lint` | Orphans / dead links |
| `ring-wiki-events` | List or append ops log |

### Apply migration

```bash
psql "$DATABASE_URL" -f data/migrations/040_wiki_pages.sql
```

Also present in `data/schema.sql` for fresh installs. No wiki-specific env vars are required beyond the existing Postgres `DATABASE_URL` / MCP service token.

### Call WikiService from adapters only

```typescript
import * as WikiService from '@/features/wiki/wiki-service'
import { resolveWikiActor } from '@/features/wiki/resolve-wiki-actor'
import type { VaultKey } from '@/features/wiki/types'

const actor = await resolveWikiActor({
  userId: session.user.id,
  role: session.user.role,
  orderId, // when scoping a project vault
})
await WikiService.ensureTenantSchema(actor)
const vault: VaultKey = 'tenant'
const pages = await WikiService.listPages(actor, vault)
```

MCP handlers set `isAgent: true` so tenant write rules apply even if the service token role is superadmin.

### Append vs replace

```typescript
await WikiService.updatePage(actor, pageId, {
  bodyMarkdown: '## Note\nIntegrator addendum…',
  mode: 'append', // required for integrator on tenant
})
```

Wiki must not store Order Lab env secrets. Link operators to `#secrets` / project-config panels instead (`features/crm/orders/*`).

- [features/admin](/docs/features/admin.md) — Next-step: Admin console nav SSOT — Wiki lives under Content & Blog and in the right rail.

- [features/owner-project-lab](/docs/features/owner-project-lab.md) — Same-workflow: project vaults open on buyer My Projects and integrator Order Lab desks; CRM orders desk is a rail action.

- [development/ring-mcp](/docs/development/ring-mcp.md) — Depends-on: ring-wiki-* tools ride the same MCP service token as news/entity tools.

- [features/news](/docs/features/news.md) — See-also: news is Markdown shortcodes via NewsRichEditor — do not store wiki bodies there.

- [architecture/data-model](/docs/architecture/data-model.md) — Deep-dive: JSONB collection pattern (`id` + `data`) used by wiki_pages and siblings.

- [features/file-cabinet](/docs/features/file-cabinet.md) — See-also: shared FileTree helpers (`components/file-tree/tree-helpers.ts`) and the same JSONB id+data pattern on file_cabinet_* tables.

- [features/store](/docs/features/store.md) — Same-workflow: Agent Knowledge Research writes Product NODUS pages into the tenant vault.