┌─────────────────────┐        ┌──────────────────────────┐
  │   GIT REPO           │        │   PACKAGE REGISTRY        │
  │  (browse / read)     │        │  (install / resolve)      │
  │  Files tab, README,  │        │  tarballs, versions,      │
  │  commits, page.json  │        │  dependencies, dist-tags  │
  └─────────────────────┘        └──────────────────────────┘
   written by POST /files          written by `adom-wiki pkg publish`

---
name: wiki-anatomy
description: >-
  The mental model of the Adom Wiki (wiki.adom.inc): it is five familiar tools
  fused into one product keyed off a single slug per page, a git host, the
  wiki package manager (`adom-wiki pkg`), a release database, a discussion forum, pull requests,
  and discovery, plus a presentation layer. Read this to understand WHAT the wiki
  is before learning HOW to drive it. Trigger words: what is the adom wiki, how
  does the wiki work, wiki architecture, wiki mental model, git plus npm plus
  releases, wiki page is a repo, two storage layers, why both git and registry,
  wiki anatomy, explain the wiki, six tools in one.
---

Parent skill: **adom-wiki-skillpack**

# What the Adom Wiki is

The Adom Wiki looks like a wiki, but it is **six tools you already know, fused
into one**, all addressed by a single `slug` per page. Understanding this is the
prerequisite for everything else, most publishing mistakes come from treating
it as one tool when it is several stacked together.

## The six tools

1. **A git host (per page).** Every page owns a real git repo. The Files tab,
   README rendering, commit log, and contributors all read from it. You push to
   it via `POST /api/v1/pages/:slug/files`, that call *is* a `git commit`.

2. **`adom-wiki pkg`, an npm-style package manager.** Alongside the git repo, each page
   can carry a package: versioned tarballs, a `package.json` manifest, a
   `dependencies` map, and dist-tags. `adom-wiki pkg install <slug>` resolves and
   installs dependencies transitively, just like `npm i`. `adom-wiki pkg update`
   upgrades everything installed.

3. **A release database.** Like GitHub Releases: a page can attach versioned,
   downloadable assets (per-platform binaries) via `adom-wiki release upload`. This
   is how closed-source apps ship a compiled binary without shipping source.

4. **A discussion forum.** Each page has discussions + threaded replies, the
   GitHub-Issues equivalent, for questions, bug reports, and feature requests.

5. **Pull requests.** Community members propose edits to a page's repo; the owner
   reviews and merges. The contribution path for a wiki you don't own.

6. **Discovery.** How a page/skill gets FOUND, search, the `/discover` endpoint's
   trigger matching, and local installed-skill matching. A first-class pillar: a
   page that can't be discovered may as well not exist. The **scoring/trending**
   signals (stars, high-fives, installs) feed discovery's ranking. See
   **wiki-discovery** (and **wiki-scoring** for the signals).

## The presentation layer

- **Presentation.** The Overview tab renders either a plain `README.md` or a
  custom `readme.html` for full control. A page whose source is private can also
  carry a **private readme** so the public still sees docs. See **wiki-readme**
  and **wiki-visibility**.

## The one idea that prevents most bugs: two independent storage layers

```
  ┌─────────────────────┐        ┌──────────────────────────┐
  │   GIT REPO           │        │   PACKAGE REGISTRY        │
  │  (browse / read)     │        │  (install / resolve)      │
  │  Files tab, README,  │        │  tarballs, versions,      │
  │  commits, page.json  │        │  dependencies, dist-tags  │
  └─────────────────────┘        └──────────────────────────┘
   written by POST /files          written by `adom-wiki pkg publish`
```

They are **not** synchronized. `adom-wiki pkg publish` does **not** push your source to
the git repo, and pushing files does **not** create a tarball. A correct publish
writes **both**. Doing only one leaves the page half-broken (placeholder Files
tab, or a README that won't install). This is the single most common failure ,
the **wiki-api** and **wiki-publish-safely** skills exist to make you do both,
in the right order.

Same split as the rest of the world: GitHub (repo) + npm (registry). The wiki
just puts both behind one slug.

## ⛔ Two storage layers: the files blob store vs the git page repo

A page has TWO stores, and they are NOT synced:

- the **files blob API** (`POST /api/v1/pages/<slug>/files`), and
- the **git page repo**, which is what the **Files tab renders** and what `adom-wiki repo *` reads
  and writes.

A raw `curl POST .../files` can return **200 while the Files tab keeps serving the OLD content**,
because the git repo was never updated. This burned a real session: nine docs "published" with 200s,
all stale on the page.

**Rule: page content (README, docs, images) goes through `adom-wiki repo push --files ...`,** then
verify with `adom-wiki repo show <ref> <path>`. Use the raw files API only for things a tool
explicitly reads from it (e.g. a bridge manifest an installer fetches by URL).