From f2f9590cffcbc28333aece56129b5631d3b74f7d Mon Sep 17 00:00:00 2001
From: DanMat <dannymatthew@gmail.com>
Date: Sun, 30 Aug 2026 19:19:07 -0400
Subject: [PATCH] =?UTF-8?q?feat:=20item=20master=20=E2=80=94=20a=20SKU's?=
 =?UTF-8?q?=20sellable=20item=20+=20category=20taxonomy=20(ADR=200022)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

For retail (a grocery sells its inventory as-is), a SKU can now optionally
carry a sellable *item* record — name, price, unit, description, image,
active/featured flags — alongside its ledger stock, plus a two-level
category taxonomy. Additive: a SKU can have stock with no item and vice
versa, so a pure-ledger user is unaffected. Keyed by the opaque sku_code
with no FK into core (image is a soft media-id ref resolved at render).

- Schema: inventory_item + inventory_category (migration 003_items),
  superseding the "catalog lives in content" docblocks (ADR 0022).
- Catalog service: item/category CRUD with the pinned controls — store
  raw / escape on render, non-negative decimal price, media-id soft ref,
  field allow-list (no over-posting), category parent-must-exist + two-
  level depth (cycles impossible), delete blocked while referenced.
- MCP: inventory_item_set/get + category_set/get + categories, gated
  inventory:write/read (deletes stay admin-only — a recorded deferral).
- Admin: a Catalog page (item + category management), inventory:write +
  CSRF, one nonce'd <style> block (admin CSP), mobile-reflow tables.
- Guide updated to teach the item master.

Tests: item override, raw storage, price/media-id/category validation,
content-token-cannot-write, over-posting ignored, two-level depth,
delete-block, slug allow-list, admin escaping + CSP-clean + reflow.
PHPStan L max, 68 tests, cs-fixer all green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/Catalog.php                  | 481 +++++++++++++++++++++++++++++++
 src/CatalogAdmin.php             | 257 +++++++++++++++++
 src/CategoryInUse.php            |  18 ++
 src/Guide.php                    |  27 +-
 src/InventoryPlugin.php          |  90 +++++-
 src/InventoryToolset.php         | 132 ++++++++-
 src/Schema.php                   |  54 +++-
 tests/CatalogAdminTest.php       | 111 +++++++
 tests/CatalogTest.php            | 159 ++++++++++
 tests/InventoryToolsetTest.php   |  87 +++++-
 tests/PackageIntegrationTest.php |   2 +-
 11 files changed, 1401 insertions(+), 17 deletions(-)
 create mode 100644 src/Catalog.php
 create mode 100644 src/CatalogAdmin.php
 create mode 100644 src/CategoryInUse.php
 create mode 100644 tests/CatalogAdminTest.php
 create mode 100644 tests/CatalogTest.php

diff --git a/src/Catalog.php b/src/Catalog.php
new file mode 100644
index 0000000..a57c20e
--- /dev/null
+++ b/src/Catalog.php
@@ -0,0 +1,481 @@
+<?php
+
+declare(strict_types=1);
+
+namespace NimbusCMS\Inventory;
+
+use Nimbus\Plugin\PluginStorage;
+
+/**
+ * The item master (ADR 0022) — a SKU's optional sellable attributes and a
+ * lightweight two-level category taxonomy, alongside the ledger's stock.
+ *
+ * This is the retail counterpart to a content catalog: for goods you stock and
+ * sell as-is, the SKU *is* the product. It is deliberately additive — a SKU can
+ * carry stock with no item here, and an item with no stock — so a pure-ledger
+ * user is unaffected.
+ *
+ * Every write is the security boundary the review pinned:
+ *  - **Store raw, escape on render.** `name`/`description`/`unit` are kept
+ *    byte-exact (no lossy pre-escape); the render layer escapes (`View::e`). So
+ *    this class never HTML-encodes on the way in.
+ *  - **Price is validated** to a non-negative decimal (≤2 places) — never a raw
+ *    string into DECIMAL, never negative.
+ *  - **Field allow-list.** A row is built only from known keys; `sku_code` is the
+ *    addressed key and timestamps are server-set, so no arbitrary key can be
+ *    mass-assigned.
+ *  - **`image_media_id` is a soft ref** (a nullable int into core's public media
+ *    library) resolved defensively at render — no FK, no traversal.
+ *  - **Category integrity.** A parent must exist and be top-level (fixing depth
+ *    at two and making cycles impossible); a category in use can't be deleted.
+ */
+final class Catalog
+{
+    /** @param \Closure():PluginStorage $storage resolved lazily, so construction runs no query */
+    public function __construct(private \Closure $storage)
+    {
+    }
+
+    // --- items -----------------------------------------------------------
+
+    /**
+     * Create or update an item by its SKU code. Reads only known fields from
+     * `$fields` (the over-posting guard); unset fields keep their stored value on
+     * an update, or take their column default on a create.
+     *
+     * @param array<string,mixed> $fields
+     */
+    public function saveItem(string $sku, array $fields, string $now): void
+    {
+        $sku = trim($sku);
+        if ($sku === '') {
+            throw new \InvalidArgumentException('A SKU code is required.');
+        }
+
+        $existing = $this->getItem($sku);
+
+        // Build the row from the allow-list only, defaulting to the existing row
+        // (update) or the column defaults (create).
+        $name        = $this->name($fields, $existing);
+        $price       = $this->price($fields, $existing);
+        $unit        = $this->optStr($fields, 'unit', $existing, 32);
+        $description = $this->description($fields, $existing);
+        $imageId     = $this->optId($fields, 'image_media_id', $existing);
+        $categoryId  = $this->categoryRef($fields, $existing);
+        $active      = $this->flag($fields, 'active', $existing, true);
+        $featured    = $this->flag($fields, 'featured', $existing, false);
+
+        $this->storage()->execute(
+            'INSERT INTO ' . Schema::ITEM . '
+                (sku_code, name, price, unit, description, image_media_id, category_id, active, featured, created_at, updated_at)
+             VALUES (:sku, :name, :price, :unit, :description, :image, :category, :active, :featured, :created, :updated)
+             ON DUPLICATE KEY UPDATE
+                name = :name2, price = :price2, unit = :unit2, description = :description2,
+                image_media_id = :image2, category_id = :category2, active = :active2,
+                featured = :featured2, updated_at = :updated2',
+            [
+                'sku' => $sku, 'name' => $name, 'price' => $price, 'unit' => $unit,
+                'description' => $description, 'image' => $imageId, 'category' => $categoryId,
+                'active' => $active, 'featured' => $featured, 'created' => $now, 'updated' => $now,
+                'name2' => $name, 'price2' => $price, 'unit2' => $unit, 'description2' => $description,
+                'image2' => $imageId, 'category2' => $categoryId, 'active2' => $active,
+                'featured2' => $featured, 'updated2' => $now,
+            ],
+        );
+    }
+
+    /**
+     * One item by SKU, or null. Values are returned raw (unescaped) — the render
+     * layer escapes; this is the source of truth, not a view.
+     *
+     * @return array{sku_code:string,name:string,price:string,unit:?string,description:?string,image_media_id:?int,category_id:?int,active:bool,featured:bool,created_at:string,updated_at:string}|null
+     */
+    public function getItem(string $sku): ?array
+    {
+        $row = $this->storage()->selectOne(
+            'SELECT sku_code, name, price, unit, description, image_media_id, category_id, active, featured, created_at, updated_at
+             FROM ' . Schema::ITEM . ' WHERE sku_code = :sku',
+            ['sku' => trim($sku)],
+        );
+        return $row === null ? null : $this->hydrateItem($row);
+    }
+
+    /**
+     * Items for the admin list, most-recent first, optionally filtered to those
+     * whose SKU or name contains `$q` (bound LIKE — no string-built SQL).
+     *
+     * @return list<array{sku_code:string,name:string,price:string,unit:?string,description:?string,image_media_id:?int,category_id:?int,active:bool,featured:bool,created_at:string,updated_at:string}>
+     */
+    public function allItems(?string $q = null): array
+    {
+        $q      = $q !== null ? trim($q) : '';
+        $where  = $q === '' ? '' : ' WHERE sku_code LIKE :q OR name LIKE :q2';
+        $params = $q === '' ? [] : ['q' => '%' . $q . '%', 'q2' => '%' . $q . '%'];
+
+        $rows = $this->storage()->select(
+            'SELECT sku_code, name, price, unit, description, image_media_id, category_id, active, featured, created_at, updated_at
+             FROM ' . Schema::ITEM . $where . ' ORDER BY updated_at DESC, sku_code',
+            $params,
+        );
+        return array_map($this->hydrateItem(...), $rows);
+    }
+
+    /** Delete an item by SKU; returns the number of rows removed (0 if none). */
+    public function deleteItem(string $sku): int
+    {
+        return $this->storage()->execute(
+            'DELETE FROM ' . Schema::ITEM . ' WHERE sku_code = :sku',
+            ['sku' => trim($sku)],
+        );
+    }
+
+    // --- categories ------------------------------------------------------
+
+    /**
+     * Create (id null) or rename/reparent (id given) a category. `parentId` must
+     * reference an existing top-level category and may not be the category itself;
+     * a category that is a parent of others cannot be given a parent (two levels).
+     *
+     * @return int the category id
+     */
+    public function saveCategory(?int $id, string $name, ?int $parentId, string $now): int
+    {
+        $name = trim($name);
+        if ($name === '') {
+            throw new \InvalidArgumentException('A category name is required.');
+        }
+        if (mb_strlen($name) > 120) {
+            throw new \InvalidArgumentException('A category name must be 120 characters or fewer.');
+        }
+
+        $parentId = $this->validParent($id, $parentId);
+        $slug     = $this->uniqueSlug($this->slugify($name), $id);
+
+        if ($id === null) {
+            return $this->storage()->insert(
+                'INSERT INTO ' . Schema::CATEGORY . ' (name, slug, parent_id, created_at, updated_at)
+                 VALUES (:name, :slug, :parent, :created, :updated)',
+                ['name' => $name, 'slug' => $slug, 'parent' => $parentId, 'created' => $now, 'updated' => $now],
+            );
+        }
+
+        $affected = $this->storage()->execute(
+            'UPDATE ' . Schema::CATEGORY . ' SET name = :name, slug = :slug, parent_id = :parent, updated_at = :now WHERE id = :id',
+            ['name' => $name, 'slug' => $slug, 'parent' => $parentId, 'now' => $now, 'id' => $id],
+        );
+        if ($affected === 0 && $this->getCategory($id) === null) {
+            throw new \InvalidArgumentException("No category with id {$id}.");
+        }
+        return $id;
+    }
+
+    /**
+     * @return array{id:int,name:string,slug:string,parent_id:?int,created_at:string,updated_at:string}|null
+     */
+    public function getCategory(int $id): ?array
+    {
+        $row = $this->storage()->selectOne(
+            'SELECT id, name, slug, parent_id, created_at, updated_at FROM ' . Schema::CATEGORY . ' WHERE id = :id',
+            ['id' => $id],
+        );
+        return $row === null ? null : $this->hydrateCategory($row);
+    }
+
+    /**
+     * Every category, ordered as a two-level tree (each top-level followed by its
+     * children), for the admin list and the (later) storefront nav.
+     *
+     * @return list<array{id:int,name:string,slug:string,parent_id:?int,created_at:string,updated_at:string}>
+     */
+    public function allCategories(): array
+    {
+        $rows = array_map(
+            $this->hydrateCategory(...),
+            $this->storage()->select('SELECT id, name, slug, parent_id, created_at, updated_at FROM ' . Schema::CATEGORY . ' ORDER BY name'),
+        );
+
+        $tops     = array_values(array_filter($rows, static fn (array $c): bool => $c['parent_id'] === null));
+        $children = [];
+        foreach ($rows as $c) {
+            if ($c['parent_id'] !== null) {
+                $children[$c['parent_id']][] = $c;
+            }
+        }
+
+        $ordered = [];
+        foreach ($tops as $top) {
+            $ordered[] = $top;
+            foreach ($children[$top['id']] ?? [] as $child) {
+                $ordered[] = $child;
+            }
+        }
+        return $ordered;
+    }
+
+    /**
+     * Delete a category. Blocked ({@see CategoryInUse}) while a child category or
+     * any item still references it — the caller reparents/reassigns first.
+     */
+    public function deleteCategory(int $id): void
+    {
+        $s = $this->storage();
+        $childCount = $s->selectOne('SELECT COUNT(*) AS n FROM ' . Schema::CATEGORY . ' WHERE parent_id = :id', ['id' => $id]);
+        if ($childCount !== null && (int) $childCount['n'] > 0) {
+            throw new CategoryInUse($id, 'child categories');
+        }
+        $itemCount = $s->selectOne('SELECT COUNT(*) AS n FROM ' . Schema::ITEM . ' WHERE category_id = :id', ['id' => $id]);
+        if ($itemCount !== null && (int) $itemCount['n'] > 0) {
+            throw new CategoryInUse($id, 'items');
+        }
+        $s->execute('DELETE FROM ' . Schema::CATEGORY . ' WHERE id = :id', ['id' => $id]);
+    }
+
+    // --- validation / hydration -----------------------------------------
+
+    /**
+     * @param array<string,mixed>      $fields
+     * @param array<string,mixed>|null $existing
+     */
+    private function name(array $fields, ?array $existing): string
+    {
+        if (!array_key_exists('name', $fields)) {
+            if ($existing !== null) {
+                return (string) $existing['name'];
+            }
+            throw new \InvalidArgumentException('An item name is required.');
+        }
+        $name = trim((string) $fields['name']);
+        if ($name === '') {
+            throw new \InvalidArgumentException('An item name is required.');
+        }
+        if (mb_strlen($name) > 200) {
+            throw new \InvalidArgumentException('An item name must be 200 characters or fewer.');
+        }
+        return $name;
+    }
+
+    /**
+     * A non-negative decimal with up to 2 places, validated as a string (no float,
+     * no bcmath) exactly like the ledger validates quantities.
+     *
+     * @param array<string,mixed>      $fields
+     * @param array<string,mixed>|null $existing
+     */
+    private function price(array $fields, ?array $existing): string
+    {
+        if (!array_key_exists('price', $fields)) {
+            return $existing !== null ? (string) $existing['price'] : '0.00';
+        }
+        $price = trim((string) $fields['price']);
+        if ($price === '') {
+            return '0.00';
+        }
+        if (preg_match('/^\d+(\.\d{1,2})?$/', $price) !== 1) {
+            throw new \InvalidArgumentException("\"{$price}\" is not a valid price (a non-negative amount with up to 2 decimal places).");
+        }
+        return $price;
+    }
+
+    /**
+     * @param array<string,mixed>      $fields
+     * @param array<string,mixed>|null $existing
+     */
+    private function description(array $fields, ?array $existing): ?string
+    {
+        if (!array_key_exists('description', $fields)) {
+            return $existing !== null ? ($existing['description'] === null ? null : (string) $existing['description']) : null;
+        }
+        // Plain text v1 (no HTML): stored raw and byte-exact — the render layer
+        // escapes. Capped to a sane length so a write can't be used to bloat a row.
+        $desc = (string) $fields['description'];
+        if (mb_strlen($desc) > 5000) {
+            throw new \InvalidArgumentException('A description must be 5000 characters or fewer.');
+        }
+        $desc = trim($desc);
+        return $desc === '' ? null : $desc;
+    }
+
+    /**
+     * @param array<string,mixed>      $fields
+     * @param array<string,mixed>|null $existing
+     */
+    private function optStr(array $fields, string $key, ?array $existing, int $max): ?string
+    {
+        if (!array_key_exists($key, $fields)) {
+            return $existing !== null ? ($existing[$key] === null ? null : (string) $existing[$key]) : null;
+        }
+        $v = trim((string) $fields[$key]);
+        if ($v === '') {
+            return null;
+        }
+        if (mb_strlen($v) > $max) {
+            throw new \InvalidArgumentException("\"{$key}\" must be {$max} characters or fewer.");
+        }
+        return $v;
+    }
+
+    /**
+     * A nullable positive id (image media ref). Empty/absent → null; a
+     * non-positive or non-numeric value is rejected rather than silently stored.
+     *
+     * @param array<string,mixed>      $fields
+     * @param array<string,mixed>|null $existing
+     */
+    private function optId(array $fields, string $key, ?array $existing): ?int
+    {
+        if (!array_key_exists($key, $fields)) {
+            return $existing !== null ? ($existing[$key] === null ? null : (int) $existing[$key]) : null;
+        }
+        $raw = trim((string) $fields[$key]);
+        if ($raw === '') {
+            return null;
+        }
+        if (preg_match('/^\d+$/', $raw) !== 1 || (int) $raw < 1) {
+            throw new \InvalidArgumentException("\"{$key}\" must be a positive whole number or blank.");
+        }
+        return (int) $raw;
+    }
+
+    /**
+     * The category a new/updated item points at: null, or an id that must exist in
+     * this install (a soft ref, checked at write so a dangling id can't be stored).
+     *
+     * @param array<string,mixed>      $fields
+     * @param array<string,mixed>|null $existing
+     */
+    private function categoryRef(array $fields, ?array $existing): ?int
+    {
+        $id = $this->optId($fields, 'category_id', $existing);
+        if ($id !== null && $this->getCategory($id) === null) {
+            throw new \InvalidArgumentException("No category with id {$id}.");
+        }
+        return $id;
+    }
+
+    /**
+     * @param array<string,mixed>      $fields
+     * @param array<string,mixed>|null $existing
+     */
+    private function flag(array $fields, string $key, ?array $existing, bool $default): int
+    {
+        if (!array_key_exists($key, $fields)) {
+            if ($existing !== null) {
+                return (bool) $existing[$key] ? 1 : 0;
+            }
+            return $default ? 1 : 0;
+        }
+        return $this->truthy($fields[$key]) ? 1 : 0;
+    }
+
+    private function truthy(mixed $v): bool
+    {
+        if (is_bool($v)) {
+            return $v;
+        }
+        if (is_int($v)) {
+            return $v === 1;
+        }
+        if (is_string($v)) {
+            return in_array(strtolower(trim($v)), ['1', 'true', 'on', 'yes'], true);
+        }
+        return false;
+    }
+
+    /**
+     * Resolve and validate a proposed parent for category `$id` (null on create):
+     * it must exist, be top-level, and not be the category itself.
+     */
+    private function validParent(?int $id, ?int $parentId): ?int
+    {
+        if ($parentId === null) {
+            return null;
+        }
+        if ($id !== null && $parentId === $id) {
+            throw new \InvalidArgumentException('A category cannot be its own parent.');
+        }
+        $parent = $this->getCategory($parentId);
+        if ($parent === null) {
+            throw new \InvalidArgumentException("No category with id {$parentId} to be a parent.");
+        }
+        if ($parent['parent_id'] !== null) {
+            throw new \InvalidArgumentException('Categories are only two levels deep — the chosen parent is already a child.');
+        }
+        // A category that already has children can't itself become a child.
+        if ($id !== null) {
+            $hasChildren = $this->storage()->selectOne('SELECT COUNT(*) AS n FROM ' . Schema::CATEGORY . ' WHERE parent_id = :id', ['id' => $id]);
+            if ($hasChildren !== null && (int) $hasChildren['n'] > 0) {
+                throw new \InvalidArgumentException('This category has children, so it must stay top-level.');
+            }
+        }
+        return $parentId;
+    }
+
+    /** Lowercase, allow-list to `[a-z0-9-]`, collapse and trim dashes. */
+    private function slugify(string $name): string
+    {
+        $slug = strtolower($name);
+        $slug = preg_replace('/[^a-z0-9]+/', '-', $slug) ?? '';
+        $slug = trim($slug, '-');
+        return $slug === '' ? 'category' : $slug;
+    }
+
+    /** Ensure the slug is unique (excluding this category), suffixing -2, -3, … */
+    private function uniqueSlug(string $base, ?int $excludeId): string
+    {
+        $slug = $base;
+        $n    = 1;
+        while (true) {
+            $row = $this->storage()->selectOne(
+                'SELECT id FROM ' . Schema::CATEGORY . ' WHERE slug = :slug' . ($excludeId !== null ? ' AND id <> :id' : ''),
+                $excludeId !== null ? ['slug' => $slug, 'id' => $excludeId] : ['slug' => $slug],
+            );
+            if ($row === null) {
+                return $slug;
+            }
+            $n++;
+            $slug = $base . '-' . $n;
+        }
+    }
+
+    /**
+     * @param array<string,mixed> $row
+     * @return array{sku_code:string,name:string,price:string,unit:?string,description:?string,image_media_id:?int,category_id:?int,active:bool,featured:bool,created_at:string,updated_at:string}
+     */
+    private function hydrateItem(array $row): array
+    {
+        return [
+            'sku_code'       => (string) $row['sku_code'],
+            'name'           => (string) $row['name'],
+            'price'          => (string) $row['price'],
+            'unit'           => $row['unit'] === null ? null : (string) $row['unit'],
+            'description'    => $row['description'] === null ? null : (string) $row['description'],
+            'image_media_id' => $row['image_media_id'] === null ? null : (int) $row['image_media_id'],
+            'category_id'    => $row['category_id'] === null ? null : (int) $row['category_id'],
+            'active'         => (bool) $row['active'],
+            'featured'       => (bool) $row['featured'],
+            'created_at'     => (string) $row['created_at'],
+            'updated_at'     => (string) $row['updated_at'],
+        ];
+    }
+
+    /**
+     * @param array<string,mixed> $row
+     * @return array{id:int,name:string,slug:string,parent_id:?int,created_at:string,updated_at:string}
+     */
+    private function hydrateCategory(array $row): array
+    {
+        return [
+            'id'         => (int) $row['id'],
+            'name'       => (string) $row['name'],
+            'slug'       => (string) $row['slug'],
+            'parent_id'  => $row['parent_id'] === null ? null : (int) $row['parent_id'],
+            'created_at' => (string) $row['created_at'],
+            'updated_at' => (string) $row['updated_at'],
+        ];
+    }
+
+    private function storage(): PluginStorage
+    {
+        return ($this->storage)();
+    }
+}
diff --git a/src/CatalogAdmin.php b/src/CatalogAdmin.php
new file mode 100644
index 0000000..4ab1b08
--- /dev/null
+++ b/src/CatalogAdmin.php
@@ -0,0 +1,257 @@
+<?php
+
+declare(strict_types=1);
+
+namespace NimbusCMS\Inventory;
+
+/**
+ * The Catalog admin page (ADR 0022) — manage the sellable *item* record for a SKU
+ * (name, price, category, unit, image, flags) and the two-level category
+ * taxonomy. The merchandising counterpart to the stock workbench: kept on its own
+ * page so the ops view (on-hand/movements) and the catalog view stay focused, and
+ * each reads cleanly on a phone.
+ *
+ * Every author value is escaped on the way out ({@see e}); the store keeps it raw
+ * (ADR 0022 — store raw, escape on render). Styling lives in one nonce-carrying
+ * `<style>` block because the admin CSP is nonce-only for `style-src`.
+ */
+final class CatalogAdmin
+{
+    private const NOTICES = [
+        'item-saved'    => ['ok', 'Item saved.'],
+        'item-deleted'  => ['ok', 'Item deleted.'],
+        'cat-saved'     => ['ok', 'Category saved.'],
+        'cat-deleted'   => ['ok', 'Category deleted.'],
+        'cat-inuse'     => ['err', 'That category is still in use — reassign its items or child categories first.'],
+        'badprice'      => ['err', 'Enter a valid price — a non-negative amount with up to 2 decimal places.'],
+        'badcat'        => ['err', 'Check the category details and try again.'],
+        'invalid'       => ['err', 'Check the details and try again.'],
+    ];
+
+    public function __construct(private Catalog $catalog)
+    {
+    }
+
+    /**
+     * @param string  $csrf   CSRF token for the forms
+     * @param ?string $notice a fixed notice code from the ?ok=/?err= redirect
+     * @param ?string $edit   a SKU to load into the item form (from ?edit=)
+     * @param ?string $editCat a category id to load into the category form (from ?editcat=)
+     * @param string  $nonce  the request CSP nonce
+     */
+    public function render(string $csrf = '', ?string $notice = null, ?string $edit = null, ?string $editCat = null, string $nonce = ''): string
+    {
+        $categories = $this->catalog->allCategories();
+        $catName    = [];
+        foreach ($categories as $c) {
+            $catName[$c['id']] = $c['name'];
+        }
+
+        $editItem = ($edit !== null && trim($edit) !== '') ? $this->catalog->getItem(trim($edit)) : null;
+        $editCatId = ($editCat !== null && preg_match('/^\d+$/', trim($editCat)) === 1) ? (int) trim($editCat) : null;
+        $editCategory = $editCatId !== null ? $this->catalog->getCategory($editCatId) : null;
+
+        $html = $this->styles($nonce)
+            . '<div class="nb-page-head"><h1>Catalog</h1></div>' . $this->notice($notice)
+            . '<p class="nb-muted cx-intro">The sellable item behind each SKU — name, price, category and image — the source of truth a storefront reads. '
+            . 'The same records an agent manages over the <code>inventory_item_*</code> tools.</p>';
+
+        // Item editor + list.
+        $html .= '<h2>' . ($editItem !== null ? 'Edit item' : 'Add an item') . '</h2>';
+        $html .= $this->itemForm($csrf, $categories, $editItem);
+        $html .= '<h2 class="cx-mt2">Items</h2>' . $this->itemList($catName);
+
+        // Category editor + list.
+        $html .= '<h2 class="cx-mt2">' . ($editCategory !== null ? 'Edit category' : 'Add a category') . '</h2>';
+        $html .= $this->categoryForm($csrf, $categories, $editCategory);
+        $html .= '<h2 class="cx-mt15">Categories</h2>' . $this->categoryList($csrf, $categories, $catName);
+
+        return $html;
+    }
+
+    /**
+     * @param list<array{id:int,name:string,slug:string,parent_id:?int,created_at:string,updated_at:string}> $categories
+     * @param array{sku_code:string,name:string,price:string,unit:?string,description:?string,image_media_id:?int,category_id:?int,active:bool,featured:bool,created_at:string,updated_at:string}|null $item
+     */
+    private function itemForm(string $csrf, array $categories, ?array $item): string
+    {
+        // Null-safe locals up front, so the markup never indexes a possibly-null
+        // $item (a create renders blank fields; an edit renders the stored values).
+        $editing  = $item !== null;
+        $e        = fn (string $s): string => $this->e($s);
+        $sku      = $editing ? $item['sku_code'] : '';
+        $name     = $editing ? $item['name'] : '';
+        $price    = $editing ? $item['price'] : '';
+        $unit     = ($editing && $item['unit'] !== null) ? $item['unit'] : '';
+        $desc     = ($editing && $item['description'] !== null) ? $item['description'] : '';
+        $image    = ($editing && $item['image_media_id'] !== null) ? (string) $item['image_media_id'] : '';
+        $catId    = $editing ? $item['category_id'] : null;
+        $active   = !$editing || $item['active'];
+        $featured = $editing && $item['featured'];
+
+        $skuField = $editing
+            ? '<input type="hidden" name="sku" value="' . $e($sku) . '">'
+              . '<div class="nb-field"><label>SKU</label><p class="cx-fixed"><code>' . $e($sku) . '</code></p></div>'
+            : '<div class="nb-field"><label for="cx-sku">SKU code</label>'
+              . '<input type="text" id="cx-sku" name="sku" placeholder="e.g. banana-loose" required></div>';
+
+        return '<form class="nb-form-card cx-form" method="post" action="/admin/catalog/item-save">'
+            . '<input type="hidden" name="_token" value="' . $e($csrf) . '">'
+            . $skuField
+            . '<div class="nb-field"><label for="cx-name">Name</label>'
+            . '<input type="text" id="cx-name" name="name" value="' . $e($name) . '" placeholder="e.g. Bananas (loose)" required></div>'
+            . '<div class="cx-row">'
+            . '<div class="nb-field cx-half"><label for="cx-price">Price</label>'
+            . '<input type="text" id="cx-price" name="price" inputmode="decimal" value="' . $e($price) . '" placeholder="e.g. 0.35"></div>'
+            . '<div class="nb-field cx-half"><label for="cx-unit">Unit</label>'
+            . '<input type="text" id="cx-unit" name="unit" value="' . $e($unit) . '" placeholder="e.g. each, kg"></div>'
+            . '</div>'
+            . '<div class="nb-field"><label for="cx-category">Category</label>'
+            . $this->categorySelect('category_id', $categories, $catId, true)
+            . '</div>'
+            . '<div class="nb-field"><label for="cx-image">Image (media ID)</label>'
+            . '<input type="text" id="cx-image" name="image_media_id" inputmode="numeric" value="' . $e($image) . '" placeholder="optional"></div>'
+            . '<div class="nb-field"><label for="cx-desc">Description</label>'
+            . '<textarea id="cx-desc" name="description" rows="3" placeholder="Plain text — no HTML">' . $e($desc) . '</textarea></div>'
+            . '<div class="cx-checks">'
+            . '<label class="cx-check"><input type="checkbox" name="active" value="1"' . ($active ? ' checked' : '') . '> Active (sellable)</label>'
+            . '<label class="cx-check"><input type="checkbox" name="featured" value="1"' . ($featured ? ' checked' : '') . '> Featured</label>'
+            . '</div>'
+            . '<div class="cx-actions"><button type="submit" class="nb-btn nb-btn-primary">' . ($editing ? 'Save item' : 'Add item') . '</button>'
+            . ($editing ? ' <a class="nb-btn" href="/admin/catalog">Cancel</a>' : '')
+            . '</div></form>'
+            . ($editing
+                ? '<form class="cx-form cx-delete" method="post" action="/admin/catalog/item-delete" data-confirm="Delete this item? Its stock ledger is kept.">'
+                  . '<input type="hidden" name="_token" value="' . $e($csrf) . '">'
+                  . '<input type="hidden" name="sku" value="' . $e($sku) . '">'
+                  . '<button type="submit" class="nb-link-danger">Delete this item</button></form>'
+                : '');
+    }
+
+    /** @param array<int,string> $catName category id → name, for display */
+    private function itemList(array $catName): string
+    {
+        $items = $this->catalog->allItems();
+        if ($items === []) {
+            return '<p class="nb-muted">No items yet. Add one above, or use the <code>inventory_item_set</code> tool.</p>';
+        }
+
+        $html = '<div class="nb-table-wrap nb-stack"><table class="nb-table"><thead><tr>'
+            . '<th>SKU</th><th>Name</th><th class="cx-r">Price</th><th>Category</th><th>Status</th><th></th></tr></thead><tbody>';
+        foreach ($items as $it) {
+            $cat = $it['category_id'] !== null ? ($catName[$it['category_id']] ?? '#' . $it['category_id']) : '—';
+            $badges = ($it['active'] ? '<span class="nb-badge nb-badge-ok">Active</span>' : '<span class="nb-badge nb-badge-muted">Hidden</span>')
+                . ($it['featured'] ? ' <span class="nb-badge nb-badge-official">Featured</span>' : '');
+            $html .= '<tr><td data-label="SKU"><code>' . $this->e($it['sku_code']) . '</code></td>'
+                . '<td data-label="Name">' . $this->e($it['name']) . '</td>'
+                . '<td data-label="Price" class="cx-r">' . $this->e($it['price']) . ($it['unit'] !== null ? ' <span class="nb-muted">/ ' . $this->e($it['unit']) . '</span>' : '') . '</td>'
+                . '<td data-label="Category">' . $this->e($cat) . '</td>'
+                . '<td data-label="Status">' . $badges . '</td>'
+                . '<td data-label="" class="cx-r"><a class="nb-btn nb-btn-sm" href="/admin/catalog?edit=' . $this->e(rawurlencode($it['sku_code'])) . '">Edit</a></td></tr>';
+        }
+        return $html . '</tbody></table></div>';
+    }
+
+    /**
+     * @param list<array{id:int,name:string,slug:string,parent_id:?int,created_at:string,updated_at:string}> $categories
+     * @param array{id:int,name:string,slug:string,parent_id:?int,created_at:string,updated_at:string}|null $cat
+     */
+    private function categoryForm(string $csrf, array $categories, ?array $cat): string
+    {
+        // A category being edited can't be its own parent; only top-level
+        // categories (other than this one) can be parents.
+        $parents = array_values(array_filter(
+            $categories,
+            static fn (array $c): bool => $c['parent_id'] === null && ($cat === null || $c['id'] !== $cat['id']),
+        ));
+
+        return '<form class="nb-form-card cx-form" method="post" action="/admin/catalog/category-save">'
+            . '<input type="hidden" name="_token" value="' . $this->e($csrf) . '">'
+            . ($cat !== null ? '<input type="hidden" name="id" value="' . $cat['id'] . '">' : '')
+            . '<div class="nb-field"><label for="cx-catname">Name</label>'
+            . '<input type="text" id="cx-catname" name="name" value="' . $this->e($cat['name'] ?? '') . '" placeholder="e.g. Fruit &amp; Veg" required></div>'
+            . '<div class="nb-field"><label for="cx-catparent">Parent</label>'
+            . $this->categorySelect('parent_id', $parents, $cat['parent_id'] ?? null, true, 'cx-catparent')
+            . '<p class="nb-muted cx-hint">Leave as “Top level” for a main category. Categories are two levels deep.</p></div>'
+            . '<div class="cx-actions"><button type="submit" class="nb-btn nb-btn-primary">' . ($cat !== null ? 'Save category' : 'Add category') . '</button>'
+            . ($cat !== null ? ' <a class="nb-btn" href="/admin/catalog">Cancel</a>' : '')
+            . '</div></form>';
+    }
+
+    /**
+     * @param list<array{id:int,name:string,slug:string,parent_id:?int,created_at:string,updated_at:string}> $categories
+     * @param array<int,string> $catName
+     */
+    private function categoryList(string $csrf, array $categories, array $catName): string
+    {
+        if ($categories === []) {
+            return '<p class="nb-muted">No categories yet.</p>';
+        }
+        $html = '<div class="nb-table-wrap nb-stack"><table class="nb-table"><thead><tr>'
+            . '<th>Name</th><th>Slug</th><th></th></tr></thead><tbody>';
+        foreach ($categories as $c) {
+            $label = $c['parent_id'] !== null
+                ? '<span class="cx-child">↳</span> ' . $this->e($c['name']) . ' <span class="nb-muted cx-parent">in ' . $this->e($catName[$c['parent_id']] ?? '#' . $c['parent_id']) . '</span>'
+                : '<strong>' . $this->e($c['name']) . '</strong>';
+            $html .= '<tr><td data-label="Name">' . $label . '</td>'
+                . '<td data-label="Slug"><code>' . $this->e($c['slug']) . '</code></td>'
+                . '<td data-label="" class="cx-r"><a class="nb-btn nb-btn-sm" href="/admin/catalog?editcat=' . $c['id'] . '">Edit</a> '
+                . '<form class="cx-inline" method="post" action="/admin/catalog/category-delete" data-confirm="Delete this category?">'
+                . '<input type="hidden" name="_token" value="' . $this->e($csrf) . '">'
+                . '<input type="hidden" name="id" value="' . $c['id'] . '">'
+                . '<button type="submit" class="nb-link-danger">Delete</button></form></td></tr>';
+        }
+        return $html . '</tbody></table></div>';
+    }
+
+    /**
+     * A category `<select>` (optionally with a "none/top-level" first option),
+     * showing children indented under their parent.
+     *
+     * @param list<array{id:int,name:string,slug:string,parent_id:?int,created_at:string,updated_at:string}> $categories
+     */
+    private function categorySelect(string $name, array $categories, ?int $selected, bool $allowNone, string $id = 'cx-category'): string
+    {
+        $out = '<select id="' . $this->e($id) . '" name="' . $this->e($name) . '">';
+        if ($allowNone) {
+            $out .= '<option value="">' . ($name === 'parent_id' ? 'Top level' : '— none —') . '</option>';
+        }
+        foreach ($categories as $c) {
+            $prefix = $c['parent_id'] !== null ? '— ' : '';
+            $sel    = ($selected !== null && $selected === $c['id']) ? ' selected' : '';
+            $out .= '<option value="' . $c['id'] . '"' . $sel . '>' . $prefix . $this->e($c['name']) . '</option>';
+        }
+        return $out . '</select>';
+    }
+
+    private function styles(string $nonce): string
+    {
+        $css = '.cx-intro{margin:-8px 0 20px}'
+            . '.cx-mt15{margin-top:1.5rem}.cx-mt2{margin-top:2rem}'
+            . '.cx-r{text-align:right}'
+            . '.cx-form{max-width:520px;margin-bottom:1.5rem}'
+            . '.cx-row{display:flex;gap:1rem;flex-wrap:wrap}.cx-half{flex:1 1 160px}'
+            . '.cx-checks{display:flex;gap:1.25rem;flex-wrap:wrap;margin:.25rem 0 1rem}'
+            . '.cx-check{display:flex;align-items:center;gap:.4rem;font-weight:500}'
+            . '.cx-actions{display:flex;gap:.5rem;flex-wrap:wrap;align-items:center}'
+            . '.cx-fixed{margin:.2rem 0 0}.cx-hint{margin:.3rem 0 0;font-size:.85rem}'
+            . '.cx-delete{margin-top:-.75rem;margin-bottom:1.5rem}'
+            . '.cx-inline{display:inline}'
+            . '.cx-child{opacity:.6}.cx-parent{font-size:.85rem}';
+        return '<style nonce="' . $this->e($nonce) . '">' . $css . '</style>';
+    }
+
+    private function notice(?string $notice): string
+    {
+        if ($notice === null || !isset(self::NOTICES[$notice])) {
+            return '';
+        }
+        [$kind, $msg] = self::NOTICES[$notice];
+        return '<div class="nb-notice nb-notice-' . ($kind === 'ok' ? 'ok' : 'error') . '">' . $this->e($msg) . '</div>';
+    }
+
+    public function e(string $v): string
+    {
+        return htmlspecialchars($v, ENT_QUOTES, 'UTF-8');
+    }
+}
diff --git a/src/CategoryInUse.php b/src/CategoryInUse.php
new file mode 100644
index 0000000..17bdd19
--- /dev/null
+++ b/src/CategoryInUse.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace NimbusCMS\Inventory;
+
+/**
+ * A category cannot be deleted while something still points at it — a child
+ * category or an item. Thrown rather than orphan-crashing or silently cascading;
+ * the caller reparents or reassigns first (ADR 0022, Slice 1 blocks the delete).
+ */
+final class CategoryInUse extends \RuntimeException
+{
+    public function __construct(public readonly int $categoryId, string $what)
+    {
+        parent::__construct("Category {$categoryId} is still in use by {$what}.");
+    }
+}
diff --git a/src/Guide.php b/src/Guide.php
index e2b03ac..fdff29c 100644
--- a/src/Guide.php
+++ b/src/Guide.php
@@ -23,8 +23,13 @@ public static function text(): string
             ## Model
 
             - A **SKU** is identified by its `sku_code` (the sku entry's code/slug).
-              The catalog (items, SKUs) lives in ordinary collections — manage it
-              with the content tools. Inventory only tracks quantities by `sku_code`.
+              A SKU can **optionally** carry a sellable **item** record here — name,
+              price, category, unit, image, flags — the source of truth a storefront
+              reads (`inventory_item_*` tools). Stock and the item are independent: a
+              SKU can have stock with no item, or an item with no stock yet. For an
+              *editorial* catalog (a café menu, a curated showcase), a content
+              collection is still the right home; the item master is for operational
+              goods you stock and sell as-is.
             - A **location** is a named place stock sits (`shelf-a`, `main`). Passing
               a new location code creates it.
             - **On-hand** is per (SKU, location). Quantities are decimals with up to
@@ -47,6 +52,24 @@ public static function text(): string
             - `inventory_stock` — on-hand, reserved, and **available** (on-hand −
               reserved) per location for a SKU.
             - `inventory_movements` — the audit trail for a SKU.
+            - `inventory_item_set` — create/update a SKU's item (name, price,
+              category, unit, image, flags). Only the fields you send change.
+            - `inventory_item_get` — a SKU's item record, or none.
+            - `inventory_category_set` — create (omit `id`) or rename/reparent (with
+              `id`) a category. `inventory_category_get` / `inventory_categories`
+              read them.
+
+            ## The item master
+
+            - **Price** is a non-negative decimal string with up to 2 places
+              (`"3.49"`). It is the source of truth a storefront and checkout read.
+            - **`description` is plain text** — no HTML; it is stored raw and escaped
+              where shown.
+            - **`image_media_id`** is a media-library id (optional); a missing image
+              simply renders nothing.
+            - **Categories are two levels.** A category with a `parent_id` is a child
+              and cannot itself be a parent. A category in use can't be deleted —
+              reassign its items/children first.
 
             ## Reservations
 
diff --git a/src/InventoryPlugin.php b/src/InventoryPlugin.php
index e998afa..37b882c 100644
--- a/src/InventoryPlugin.php
+++ b/src/InventoryPlugin.php
@@ -17,11 +17,14 @@
  * **emits events** under its own namespace (ADR 0014) — all on its **own tables**
  * (ADR 0005), touching no core data.
  *
- * The catalog (items and SKUs) lives in *content* — ordinary collections the
- * operator or an agent creates with the schema tools — so it is editable,
- * themeable and API-native. This plugin owns only the ledger: it references a SKU
- * by its opaque `sku_code`, with no foreign key into core, so a catalog change can
- * never rewrite stock history.
+ * A SKU may **optionally** carry a sellable *item* record here — name, price,
+ * category, unit, image, flags — the retail counterpart to a content catalog, for
+ * goods you stock and sell as-is (ADR 0022, {@see Catalog}). It is additive: the
+ * ledger still references a SKU only by its opaque `sku_code` with no foreign key
+ * into core (a catalog change never rewrites stock history), a SKU can carry stock
+ * with no item, and a pure-ledger user is untouched. Editorial catalogs (a menu, a
+ * showcase) still live in content collections; the item master is for operational
+ * stock you sell.
  */
 final class InventoryPlugin implements Plugin
 {
@@ -32,6 +35,7 @@ public function register(PluginContext $context): void
     {
         $context->migrations()->register('001_ledger', Schema::all());
         $context->migrations()->register('002_reservations', Schema::reservations());
+        $context->migrations()->register('003_items', Schema::items());
 
         // Grantable, wildcard-immune: nimbuscms.inventory:read / :write. Moving
         // stock is moving money — a content *:write token can never reach it.
@@ -45,8 +49,9 @@ public function register(PluginContext $context): void
         };
         $ledger       = new Ledger($storage, $emit);
         $reservations = new Reservations($storage, $ledger);
+        $catalog      = new Catalog($storage);
 
-        $context->mcp()->register(new InventoryToolset($ledger, $reservations));
+        $context->mcp()->register(new InventoryToolset($ledger, $reservations, $catalog));
 
         // Publish the reservation contract so Commerce (or any plugin) can reserve
         // stock synchronously without touching Inventory's tables (ADR 0019).
@@ -147,6 +152,79 @@ public function register(PluginContext $context): void
             }
         });
 
+        // Catalog admin (ADR 0022): manage the sellable item behind each SKU and the
+        // category taxonomy. Its own page so merchandising stays separate from the
+        // stock workbench; same `nimbuscms.inventory:write` gate + CSRF as the ledger.
+        $context->adminPages()->register(
+            'catalog',
+            'Catalog',
+            '📇',
+            static fn (Request $r, string $nonce = '', string $csrf = ''): string => (new CatalogAdmin($catalog))->render($csrf, $r->query('ok') ?? $r->query('err'), $r->query('edit'), $r->query('editcat'), $nonce),
+            self::ID . ':write',
+        );
+        $context->adminPages()->action('catalog', 'item-save', static function (Request $r) use ($catalog): Response {
+            $sku = trim((string) ($r->input('sku') ?? ''));
+            if ($sku === '') {
+                return Response::redirect('/admin/catalog?err=invalid');
+            }
+            // Build the field set from a known allow-list only — never the raw
+            // request — so no unexpected key (a forged flag/timestamp) is assigned.
+            $fields = [
+                'name'           => (string) ($r->input('name') ?? ''),
+                'price'          => (string) ($r->input('price') ?? ''),
+                'unit'           => (string) ($r->input('unit') ?? ''),
+                'description'    => (string) ($r->input('description') ?? ''),
+                'image_media_id' => (string) ($r->input('image_media_id') ?? ''),
+                'category_id'    => (string) ($r->input('category_id') ?? ''),
+                'active'         => $r->input('active') !== null,
+                'featured'       => $r->input('featured') !== null,
+            ];
+            try {
+                $catalog->saveItem($sku, $fields, date('Y-m-d H:i:s'));
+                return Response::redirect('/admin/catalog?ok=item-saved');
+            } catch (\InvalidArgumentException $e) {
+                return Response::redirect('/admin/catalog?err=' . (str_contains($e->getMessage(), 'price') ? 'badprice' : 'invalid'));
+            } catch (\Throwable) {
+                return Response::redirect('/admin/catalog?err=invalid');
+            }
+        });
+        $context->adminPages()->action('catalog', 'item-delete', static function (Request $r) use ($catalog): Response {
+            $sku = trim((string) ($r->input('sku') ?? ''));
+            if ($sku !== '') {
+                $catalog->deleteItem($sku);
+            }
+            return Response::redirect('/admin/catalog?ok=item-deleted');
+        });
+        $context->adminPages()->action('catalog', 'category-save', static function (Request $r) use ($catalog): Response {
+            $name = trim((string) ($r->input('name') ?? ''));
+            $idIn = trim((string) ($r->input('id') ?? ''));
+            $parIn = trim((string) ($r->input('parent_id') ?? ''));
+            $id     = ($idIn !== '' && ctype_digit($idIn)) ? (int) $idIn : null;
+            $parent = ($parIn !== '' && ctype_digit($parIn)) ? (int) $parIn : null;
+            try {
+                $catalog->saveCategory($id, $name, $parent, date('Y-m-d H:i:s'));
+                return Response::redirect('/admin/catalog?ok=cat-saved');
+            } catch (\InvalidArgumentException) {
+                return Response::redirect('/admin/catalog?err=badcat');
+            } catch (\Throwable) {
+                return Response::redirect('/admin/catalog?err=invalid');
+            }
+        });
+        $context->adminPages()->action('catalog', 'category-delete', static function (Request $r) use ($catalog): Response {
+            $idIn = trim((string) ($r->input('id') ?? ''));
+            if ($idIn === '' || !ctype_digit($idIn)) {
+                return Response::redirect('/admin/catalog?err=invalid');
+            }
+            try {
+                $catalog->deleteCategory((int) $idIn);
+                return Response::redirect('/admin/catalog?ok=cat-deleted');
+            } catch (CategoryInUse) {
+                return Response::redirect('/admin/catalog?err=cat-inuse');
+            } catch (\Throwable) {
+                return Response::redirect('/admin/catalog?err=invalid');
+            }
+        });
+
         // Teach any MCP agent how to drive the ledger (ADR 0013).
         $context->skills()->register('Inventory', Guide::text());
     }
diff --git a/src/InventoryToolset.php b/src/InventoryToolset.php
index 6f8a5b7..b20b7fa 100644
--- a/src/InventoryToolset.php
+++ b/src/InventoryToolset.php
@@ -12,11 +12,15 @@
 /**
  * Inventory over MCP — the agent-driven onboarding the initiative is built around.
  *
- * Six tools under the `inventory` namespace: four writes (receive, adjust, count,
- * transfer) and two reads (stock, movements). The {@see PluginToolset} base gates
+ * Tools under the `inventory` namespace: the ledger writes (receive, adjust,
+ * count, transfer) and reservation writes (reserve, release, issue); the reads
+ * (stock, movements); and the **item master** (ADR 0022) — `item_set`/`item_get`
+ * and `category_set`/`category_get`/`categories`, so an agent can manage the
+ * sellable catalog, not just the numbers. The {@see PluginToolset} base gates
  * every one on the plugin's own `nimbuscms.inventory` capability (ADR 0015/0016) —
  * a write tool needs `:write`, unreachable by a content token — so this class
- * writes no authorization code.
+ * writes no authorization code. (Deletes stay admin-only in Slice 1 — a recorded
+ * deferral of an MCP delete tool.)
  *
  * Two things the handlers guarantee, per the security review:
  *  - **`actor` and `occurred_at` are server-set** — the token's name and the
@@ -26,7 +30,7 @@
  */
 final class InventoryToolset extends PluginToolset
 {
-    public function __construct(private Ledger $ledger, private Reservations $reservations)
+    public function __construct(private Ledger $ledger, private Reservations $reservations, private Catalog $catalog)
     {
     }
 
@@ -97,6 +101,49 @@ protected function tools(): array
                 'required'   => ['sku'],
                 'properties' => ['sku' => $sku, 'limit' => ['type' => 'integer', 'description' => 'Max rows (1–500, default 50).']],
             ], $this->movements(...)),
+
+            new PluginTool('item_set', 'write', 'Create or update a SKU\'s sellable item record (name, price, category, …). Only the fields you send change; the rest keep their stored value.', [
+                'type'       => 'object',
+                'required'   => ['sku', 'name'],
+                'properties' => [
+                    'sku'            => $sku,
+                    'name'           => ['type' => 'string', 'description' => 'Display name of the item.'],
+                    'price'          => ['type' => 'string', 'description' => 'A non-negative amount, up to 2 decimals (e.g. "3.49"). Defaults to 0.'],
+                    'unit'           => ['type' => 'string', 'description' => 'Selling unit (e.g. "each", "kg", "500g pack"). Optional.'],
+                    'description'    => ['type' => 'string', 'description' => 'Plain-text description (no HTML). Optional.'],
+                    'image_media_id' => ['type' => 'integer', 'description' => 'A media-library id for the item image. Optional.'],
+                    'category_id'    => ['type' => 'integer', 'description' => 'An existing category id. Optional.'],
+                    'active'         => ['type' => 'boolean', 'description' => 'Whether the item is sellable/visible (default true).'],
+                    'featured'       => ['type' => 'boolean', 'description' => 'Whether to feature the item (default false).'],
+                ],
+            ], $this->itemSet(...)),
+
+            new PluginTool('item_get', 'read', 'The sellable item record for a SKU (name, price, category, flags), or none.', [
+                'type'       => 'object',
+                'required'   => ['sku'],
+                'properties' => ['sku' => $sku],
+            ], $this->itemGet(...)),
+
+            new PluginTool('category_set', 'write', 'Create a category (omit id) or rename/reparent one (with id). Two levels only.', [
+                'type'       => 'object',
+                'required'   => ['name'],
+                'properties' => [
+                    'id'        => ['type' => 'integer', 'description' => 'Existing category id to update; omit to create.'],
+                    'name'      => ['type' => 'string', 'description' => 'Category name.'],
+                    'parent_id' => ['type' => 'integer', 'description' => 'An existing top-level category id to nest under. Omit for a top-level category.'],
+                ],
+            ], $this->categorySet(...)),
+
+            new PluginTool('category_get', 'read', 'One category by id.', [
+                'type'       => 'object',
+                'required'   => ['id'],
+                'properties' => ['id' => ['type' => 'integer', 'description' => 'The category id.']],
+            ], $this->categoryGet(...)),
+
+            new PluginTool('categories', 'read', 'All categories, ordered as a two-level tree.', [
+                'type'       => 'object',
+                'properties' => new \stdClass(),
+            ], $this->categories(...)),
         ];
     }
 
@@ -232,6 +279,67 @@ private function movements(array $a, TokenPrincipal $p, EntryOpContext $c): arra
         return ['sku' => $sku, 'movements' => $this->ledger->movementsFor($sku, $limit)];
     }
 
+    /**
+     * @param array<string,mixed> $a
+     * @return array<string,mixed>
+     */
+    private function itemSet(array $a, TokenPrincipal $p, EntryOpContext $c): array
+    {
+        return $this->guard(function () use ($a): array {
+            $sku = $this->str($a, 'sku');
+            // saveItem reads only its own allow-listed keys from the arguments —
+            // an unknown key (or a forged sku_code/timestamp) is ignored.
+            $this->catalog->saveItem($sku, $a, $this->now());
+            return ['ok' => true, 'item' => $this->catalog->getItem($sku)];
+        });
+    }
+
+    /**
+     * @param array<string,mixed> $a
+     * @return array<string,mixed>
+     */
+    private function itemGet(array $a, TokenPrincipal $p, EntryOpContext $c): array
+    {
+        $sku = $this->str($a, 'sku');
+        return ['sku' => $sku, 'item' => $this->catalog->getItem($sku)];
+    }
+
+    /**
+     * @param array<string,mixed> $a
+     * @return array<string,mixed>
+     */
+    private function categorySet(array $a, TokenPrincipal $p, EntryOpContext $c): array
+    {
+        return $this->guard(function () use ($a): array {
+            $id       = $this->nullableInt($a, 'id');
+            $parentId = $this->nullableInt($a, 'parent_id');
+            $newId    = $this->catalog->saveCategory($id, $this->str($a, 'name'), $parentId, $this->now());
+            return ['ok' => true, 'category' => $this->catalog->getCategory($newId)];
+        });
+    }
+
+    /**
+     * @param array<string,mixed> $a
+     * @return array<string,mixed>
+     */
+    private function categoryGet(array $a, TokenPrincipal $p, EntryOpContext $c): array
+    {
+        $id = $this->nullableInt($a, 'id');
+        if ($id === null) {
+            return ['ok' => false, 'error' => 'invalid', 'message' => '"id" is required.'];
+        }
+        return ['id' => $id, 'category' => $this->catalog->getCategory($id)];
+    }
+
+    /**
+     * @param array<string,mixed> $a
+     * @return array<string,mixed>
+     */
+    private function categories(array $a, TokenPrincipal $p, EntryOpContext $c): array
+    {
+        return ['categories' => $this->catalog->allCategories()];
+    }
+
     // --- helpers ---------------------------------------------------------
 
     /**
@@ -303,6 +411,22 @@ private function strOr(array $a, string $key, string $default): string
         return $v ?? $default;
     }
 
+    /** @param array<string,mixed> $a */
+    private function nullableInt(array $a, string $key): ?int
+    {
+        $v = $a[$key] ?? null;
+        if ($v === null || $v === '') {
+            return null;
+        }
+        if (is_int($v)) {
+            return $v;
+        }
+        if (is_string($v) && preg_match('/^\d+$/', trim($v)) === 1) {
+            return (int) trim($v);
+        }
+        throw new \InvalidArgumentException("\"{$key}\" must be a whole number.");
+    }
+
     /** @param array<string,mixed> $a */
     private function nullableStr(array $a, string $key): ?string
     {
diff --git a/src/Schema.php b/src/Schema.php
index 93906d2..49c2737 100644
--- a/src/Schema.php
+++ b/src/Schema.php
@@ -27,8 +27,14 @@
  *     a new domain's reason must not be an Inventory migration.
  *  4. `lot_id` / `unit_id` are nullable from day one, so lots and serials slot in
  *     later without re-folding the ledger.
- *  5. Catalog (item/SKU) lives in *content* (collections), not here — the ledger
- *     references a SKU only by its opaque `sku_code`.
+ *  5. A SKU may **optionally** carry a sellable *item* record (name, price,
+ *     category, …) in {@see ITEM} — the retail counterpart to a content catalog,
+ *     for goods you stock and sell as-is (ADR 0022). It is additive: the ledger
+ *     still references a SKU only by its opaque `sku_code`, a SKU can have stock
+ *     with no item (and vice-versa), and a pure-ledger user's tables are
+ *     untouched. This supersedes the plugin's original "catalog lives only in
+ *     content" stance — content collections remain the catalog for *editorial*
+ *     items (a menu, a showcase); the item master is for *operational* stock.
  */
 final class Schema
 {
@@ -36,6 +42,8 @@ final class Schema
     public const LOCATION    = 'inventory_location';
     public const STOCK       = 'inventory_stock';
     public const RESERVATION = 'inventory_reservation';
+    public const ITEM        = 'inventory_item';
+    public const CATEGORY    = 'inventory_category';
 
     /**
      * The reservation overlay (Commerce slice 1). A soft hold on stock —
@@ -62,6 +70,48 @@ public static function reservations(): array
         ];
     }
 
+    /**
+     * The optional item master (ADR 0022): a SKU's sellable attributes, keyed by
+     * the same opaque `sku_code` the ledger uses — still **no** foreign key into
+     * core (`image_media_id` is a soft ref resolved defensively at render). A
+     * lightweight two-level category taxonomy backs storefront browsing; a child
+     * category (one whose `parent_id` is set) can never itself be a parent, which
+     * fixes the depth at two and makes cycles structurally impossible.
+     *
+     * @return list<string> each statement individually idempotent (ADR 0005)
+     */
+    public static function items(): array
+    {
+        return [
+            'CREATE TABLE IF NOT EXISTS ' . self::CATEGORY . ' (
+                id         BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+                name       VARCHAR(120) NOT NULL,
+                slug       VARCHAR(140) NOT NULL,
+                parent_id  BIGINT UNSIGNED NULL,
+                created_at DATETIME NOT NULL,
+                updated_at DATETIME NOT NULL,
+                UNIQUE KEY uq_category_slug (slug),
+                INDEX idx_category_parent (parent_id)
+            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4',
+
+            'CREATE TABLE IF NOT EXISTS ' . self::ITEM . ' (
+                sku_code       VARCHAR(80) NOT NULL PRIMARY KEY,
+                name           VARCHAR(200) NOT NULL,
+                price          DECIMAL(18,2) NOT NULL DEFAULT 0,
+                unit           VARCHAR(32) NULL,
+                description    TEXT NULL,
+                image_media_id BIGINT UNSIGNED NULL,
+                category_id    BIGINT UNSIGNED NULL,
+                active         TINYINT(1) NOT NULL DEFAULT 1,
+                featured       TINYINT(1) NOT NULL DEFAULT 0,
+                created_at     DATETIME NOT NULL,
+                updated_at     DATETIME NOT NULL,
+                INDEX idx_item_category (category_id),
+                INDEX idx_item_active (active)
+            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4',
+        ];
+    }
+
     /** @return list<string> each statement individually idempotent (ADR 0005) */
     public static function all(): array
     {
diff --git a/tests/CatalogAdminTest.php b/tests/CatalogAdminTest.php
new file mode 100644
index 0000000..1500554
--- /dev/null
+++ b/tests/CatalogAdminTest.php
@@ -0,0 +1,111 @@
+<?php
+
+declare(strict_types=1);
+
+namespace NimbusCMS\Inventory\Tests;
+
+use Nimbus\Database\Connection;
+use Nimbus\Plugin\PluginStorage;
+use NimbusCMS\Inventory\Catalog;
+use NimbusCMS\Inventory\CatalogAdmin;
+use NimbusCMS\Inventory\Schema;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * The Catalog admin page (ADR 0022). These lock the security + surface contracts:
+ * author values are escaped on render (never live markup), styling is one nonce'd
+ * block with no inline `style=` (the admin CSP), and tables carry `data-label`
+ * cells so they reflow on a phone rather than overflow.
+ */
+final class CatalogAdminTest extends TestCase
+{
+    private Catalog $catalog;
+    private CatalogAdmin $admin;
+    private const T = '2026-01-01 09:00:00';
+
+    protected function setUp(): void
+    {
+        $db = new Connection([
+            'host' => getenv('TEST_DB_HOST') ?: 'db',
+            'port' => (int) (getenv('TEST_DB_PORT') ?: 3306),
+            'name' => getenv('TEST_DB_NAME') ?: 'nimbus_test',
+            'user' => getenv('TEST_DB_USER') ?: 'root',
+            'pass' => ($p = getenv('TEST_DB_PASS')) !== false ? $p : 'root',
+        ]);
+        foreach (Schema::items() as $sql) {
+            $db->execute($sql);
+        }
+        $db->execute('TRUNCATE ' . Schema::ITEM);
+        $db->execute('TRUNCATE ' . Schema::CATEGORY);
+
+        $storage       = new PluginStorage($db);
+        $this->catalog = new Catalog(static fn (): PluginStorage => $storage);
+        $this->admin   = new CatalogAdmin($this->catalog);
+    }
+
+    public function test_the_item_and_category_forms_are_present(): void
+    {
+        $html = $this->admin->render('tok');
+        self::assertStringContainsString('action="/admin/catalog/item-save"', $html);
+        self::assertStringContainsString('action="/admin/catalog/category-save"', $html);
+        self::assertStringContainsString('name="_token" value="tok"', $html);
+    }
+
+    public function test_an_items_values_are_escaped_on_render_not_live_markup(): void
+    {
+        // The store keeps author input raw (proven in CatalogTest); the page must
+        // escape it — this is the standing contract the storefront (Slice 2) shares.
+        $this->catalog->saveItem('xss', ['name' => '<script>alert(1)</script>', 'price' => '1.00'], self::T);
+        $html = $this->admin->render('tok');
+
+        self::assertStringNotContainsString('<script>alert(1)</script>', $html);
+        self::assertStringContainsString('&lt;script&gt;', $html);
+    }
+
+    public function test_editing_an_item_prefills_the_form(): void
+    {
+        $this->catalog->saveItem('milk', ['name' => 'Whole Milk', 'price' => '1.20', 'unit' => 'litre'], self::T);
+        $html = $this->admin->render('tok', null, 'milk');
+
+        self::assertStringContainsString('value="Whole Milk"', $html);
+        self::assertStringContainsString('value="1.20"', $html);
+        self::assertStringContainsString('action="/admin/catalog/item-delete"', $html, 'editing offers a delete');
+    }
+
+    public function test_a_category_can_be_chosen_and_children_are_shown_nested(): void
+    {
+        $top   = $this->catalog->saveCategory(null, 'Grocery', null, self::T);
+        $this->catalog->saveCategory(null, 'Fruit', $top, self::T);
+        $html = $this->admin->render('tok');
+
+        self::assertStringContainsString('<select id="cx-category" name="category_id">', $html);
+        self::assertStringContainsString('Grocery', $html);
+        self::assertStringContainsString('Fruit', $html);
+    }
+
+    public function test_tables_reflow_on_mobile_via_data_label_cells(): void
+    {
+        $this->catalog->saveItem('apple', ['name' => 'Apple', 'price' => '0.30'], self::T);
+        $html = $this->admin->render('tok');
+        // data-label cells are how the shared admin CSS stacks a table into cards
+        // at narrow widths — their presence is the mobile-reflow contract.
+        self::assertStringContainsString('data-label="SKU"', $html);
+        self::assertStringContainsString('data-label="Price"', $html);
+    }
+
+    public function test_styling_is_a_nonced_style_block_not_inline_attributes(): void
+    {
+        $this->catalog->saveItem('a', ['name' => 'A', 'price' => '1.00'], self::T);
+        $html = $this->admin->render('tok', null, null, null, 'NONCE123');
+
+        self::assertStringContainsString('<style nonce="NONCE123">', $html, 'a nonce-carrying style block');
+        self::assertDoesNotMatchRegularExpression('/\sstyle\s*=\s*"/', $html, 'no inline style= anywhere on the page');
+    }
+
+    public function test_a_notice_code_maps_to_a_message_and_unknown_shows_nothing(): void
+    {
+        self::assertStringContainsString('Item saved.', $this->admin->render('tok', 'item-saved'));
+        self::assertStringContainsString('still in use', $this->admin->render('tok', 'cat-inuse'));
+        self::assertStringNotContainsString('nb-notice', $this->admin->render('tok', 'nonsense-code'));
+    }
+}
diff --git a/tests/CatalogTest.php b/tests/CatalogTest.php
new file mode 100644
index 0000000..718f174
--- /dev/null
+++ b/tests/CatalogTest.php
@@ -0,0 +1,159 @@
+<?php
+
+declare(strict_types=1);
+
+namespace NimbusCMS\Inventory\Tests;
+
+use Nimbus\Database\Connection;
+use Nimbus\Plugin\PluginStorage;
+use NimbusCMS\Inventory\Catalog;
+use NimbusCMS\Inventory\CategoryInUse;
+use NimbusCMS\Inventory\Schema;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * The item master service (ADR 0022). These prove the security controls the
+ * review pinned at the write boundary: raw storage, price validation, the field
+ * allow-list (no over-posting), the media-id soft ref, and category integrity.
+ */
+final class CatalogTest extends TestCase
+{
+    private Catalog $catalog;
+
+    protected function setUp(): void
+    {
+        $db = new Connection([
+            'host' => getenv('TEST_DB_HOST') ?: 'db',
+            'port' => (int) (getenv('TEST_DB_PORT') ?: 3306),
+            'name' => getenv('TEST_DB_NAME') ?: 'nimbus_test',
+            'user' => getenv('TEST_DB_USER') ?: 'root',
+            'pass' => ($p = getenv('TEST_DB_PASS')) !== false ? $p : 'root',
+        ]);
+        foreach (Schema::items() as $sql) {
+            $db->execute($sql);
+        }
+        $db->execute('TRUNCATE ' . Schema::ITEM);
+        $db->execute('TRUNCATE ' . Schema::CATEGORY);
+
+        $storage       = new PluginStorage($db);
+        $this->catalog = new Catalog(static fn (): PluginStorage => $storage);
+    }
+
+    private function now(): string
+    {
+        return date('Y-m-d H:i:s');
+    }
+
+    public function test_an_item_updates_in_place_and_keeps_unsent_fields(): void
+    {
+        $this->catalog->saveItem('milk', ['name' => 'Milk', 'price' => '1.20', 'unit' => 'litre'], $this->now());
+        // A partial update leaves price/unit untouched.
+        $this->catalog->saveItem('milk', ['name' => 'Whole Milk'], $this->now());
+
+        $item = $this->catalog->getItem('milk');
+        self::assertNotNull($item);
+        self::assertSame('Whole Milk', $item['name']);
+        self::assertSame('1.20', $item['price']);
+        self::assertSame('litre', $item['unit']);
+    }
+
+    public function test_price_must_be_a_non_negative_two_place_decimal(): void
+    {
+        foreach (['-1', '3.999', 'abc', '1e3', '  '] as $bad) {
+            try {
+                $this->catalog->saveItem('x', ['name' => 'X', 'price' => $bad], $this->now());
+                if (trim($bad) !== '') {
+                    self::fail("price \"{$bad}\" should have been rejected");
+                }
+            } catch (\InvalidArgumentException) {
+                $this->addToAssertionCount(1);
+            }
+        }
+        // Blank price defaults to 0.00 rather than erroring.
+        $this->catalog->saveItem('free', ['name' => 'Sample', 'price' => ''], $this->now());
+        self::assertSame('0.00', $this->catalog->getItem('free')['price']);
+    }
+
+    public function test_the_write_ignores_unknown_keys_and_never_mass_assigns(): void
+    {
+        // An over-posting attempt: a forged sku_code, timestamps, and a junk column.
+        $this->catalog->saveItem('real', [
+            'name'       => 'Real',
+            'price'      => '2.00',
+            'sku_code'   => 'hijacked',
+            'created_at' => '1999-01-01 00:00:00',
+            'is_admin'   => '1',
+            'nonsense'   => 'x',
+        ], $this->now());
+
+        // The addressed SKU is the one written; the forged sku_code did nothing.
+        self::assertNotNull($this->catalog->getItem('real'));
+        self::assertNull($this->catalog->getItem('hijacked'));
+        // created_at is server-set, not the forged value.
+        self::assertNotSame('1999-01-01 00:00:00', $this->catalog->getItem('real')['created_at']);
+    }
+
+    public function test_image_media_id_is_a_nullable_positive_int(): void
+    {
+        $this->catalog->saveItem('a', ['name' => 'A', 'image_media_id' => '7'], $this->now());
+        self::assertSame(7, $this->catalog->getItem('a')['image_media_id']);
+
+        $this->catalog->saveItem('b', ['name' => 'B', 'image_media_id' => ''], $this->now());
+        self::assertNull($this->catalog->getItem('b')['image_media_id']);
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->catalog->saveItem('c', ['name' => 'C', 'image_media_id' => '0'], $this->now());
+    }
+
+    public function test_an_item_category_must_exist(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->catalog->saveItem('d', ['name' => 'D', 'category_id' => '999'], $this->now());
+    }
+
+    public function test_categories_are_two_levels_and_cannot_cycle(): void
+    {
+        $top   = $this->catalog->saveCategory(null, 'Grocery', null, $this->now());
+        $child = $this->catalog->saveCategory(null, 'Fruit', $top, $this->now());
+
+        // A child cannot be a parent (third level).
+        try {
+            $this->catalog->saveCategory(null, 'Bananas', $child, $this->now());
+            self::fail('a third level should be rejected');
+        } catch (\InvalidArgumentException) {
+            $this->addToAssertionCount(1);
+        }
+
+        // A category cannot be its own parent.
+        $this->expectException(\InvalidArgumentException::class);
+        $this->catalog->saveCategory($top, 'Grocery', $top, $this->now());
+    }
+
+    public function test_a_category_in_use_cannot_be_deleted(): void
+    {
+        $top   = $this->catalog->saveCategory(null, 'Grocery', null, $this->now());
+        $child = $this->catalog->saveCategory(null, 'Fruit', $top, $this->now());
+
+        // Blocked by a child category.
+        try {
+            $this->catalog->deleteCategory($top);
+            self::fail('deleting a parent with children should be blocked');
+        } catch (CategoryInUse) {
+            $this->addToAssertionCount(1);
+        }
+
+        // Blocked by an item.
+        $this->catalog->saveItem('apple', ['name' => 'Apple', 'category_id' => (string) $child], $this->now());
+        $this->expectException(CategoryInUse::class);
+        $this->catalog->deleteCategory($child);
+    }
+
+    public function test_slugs_are_allow_listed_and_unique(): void
+    {
+        $a = $this->catalog->saveCategory(null, 'Fruit & Veg!', null, $this->now());
+        $b = $this->catalog->saveCategory(null, 'Fruit & Veg!', null, $this->now());
+
+        self::assertSame('fruit-veg', $this->catalog->getCategory($a)['slug']);
+        self::assertSame('fruit-veg-2', $this->catalog->getCategory($b)['slug'], 'a clashing slug is suffixed');
+    }
+}
diff --git a/tests/InventoryToolsetTest.php b/tests/InventoryToolsetTest.php
index 39c6bf2..c58943c 100644
--- a/tests/InventoryToolsetTest.php
+++ b/tests/InventoryToolsetTest.php
@@ -10,6 +10,7 @@
 use Nimbus\Database\Connection;
 use Nimbus\Mcp\McpError;
 use Nimbus\Plugin\PluginStorage;
+use NimbusCMS\Inventory\Catalog;
 use NimbusCMS\Inventory\InventoryToolset;
 use NimbusCMS\Inventory\Ledger;
 use NimbusCMS\Inventory\Reservations;
@@ -48,9 +49,15 @@ protected function setUp(): void
         }
         $db->execute('TRUNCATE ' . Schema::RESERVATION);
 
+        foreach (Schema::items() as $sql) {
+            $db->execute($sql);
+        }
+        $db->execute('TRUNCATE ' . Schema::ITEM);
+        $db->execute('TRUNCATE ' . Schema::CATEGORY);
+
         $storage       = new PluginStorage($db);
         $ledger        = new Ledger(static fn (): PluginStorage => $storage);
-        $this->toolset = new InventoryToolset($ledger, new Reservations(static fn (): PluginStorage => $storage, $ledger));
+        $this->toolset = new InventoryToolset($ledger, new Reservations(static fn (): PluginStorage => $storage, $ledger), new Catalog(static fn (): PluginStorage => $storage));
         $this->toolset->bindTo('nimbuscms.inventory'); // the registrar does this in prod
         $this->ctx = new EntryOpContext('127.0.0.1', '/api/v1/mcp');
 
@@ -78,13 +85,18 @@ public function test_the_tools_are_namespaced_and_split_read_from_write(): void
             'inventory_receive', 'inventory_adjust', 'inventory_count',
             'inventory_transfer', 'inventory_reserve', 'inventory_release',
             'inventory_issue', 'inventory_stock', 'inventory_movements',
+            'inventory_item_set', 'inventory_item_get', 'inventory_category_set',
+            'inventory_category_get', 'inventory_categories',
         ], $names);
     }
 
     public function test_a_read_only_token_sees_only_the_read_tools(): void
     {
         $names = array_column($this->toolset->definitions($this->principal('nimbuscms.inventory:read')), 'name');
-        self::assertSame(['inventory_stock', 'inventory_movements'], $names);
+        self::assertSame([
+            'inventory_stock', 'inventory_movements', 'inventory_item_get',
+            'inventory_category_get', 'inventory_categories',
+        ], $names);
     }
 
     public function test_a_content_token_cannot_move_stock(): void
@@ -132,4 +144,75 @@ public function test_an_oversell_comes_back_as_data_not_an_exception(): void
         self::assertFalse($out['ok']);
         self::assertSame('insufficient_stock', $out['error']);
     }
+
+    public function test_item_set_then_get_round_trips(): void
+    {
+        $write = $this->principal('nimbuscms.inventory:write');
+        $out   = $this->toolset->call('inventory_item_set', [
+            'sku' => 'banana', 'name' => 'Bananas', 'price' => '0.35', 'unit' => 'each',
+        ], $write, $this->ctx);
+        self::assertTrue($out['ok']);
+        self::assertSame('0.35', $out['item']['price']);
+
+        $read = $this->principal('nimbuscms.inventory:read');
+        $got  = $this->toolset->call('inventory_item_get', ['sku' => 'banana'], $read, $this->ctx);
+        self::assertSame('Bananas', $got['item']['name']);
+        self::assertSame('each', $got['item']['unit']);
+        self::assertTrue($got['item']['active']);
+    }
+
+    public function test_item_set_stores_markup_raw_for_escape_on_render(): void
+    {
+        // The store must keep author input byte-exact (no lossy pre-escape); the
+        // render layer escapes. This is the standing contract Slice 2 relies on.
+        $rw      = $this->principal('nimbuscms.inventory:read', 'nimbuscms.inventory:write');
+        $payload = '<img src=x onerror=alert(1)>';
+        $this->toolset->call('inventory_item_set', ['sku' => 'xss', 'name' => $payload], $rw, $this->ctx);
+
+        $got = $this->toolset->call('inventory_item_get', ['sku' => 'xss'], $rw, $this->ctx);
+        self::assertSame($payload, $got['item']['name'], 'stored raw, not HTML-encoded on the way in');
+    }
+
+    public function test_item_set_rejects_a_bad_price_as_data(): void
+    {
+        $rw = $this->principal('nimbuscms.inventory:read', 'nimbuscms.inventory:write');
+        foreach (['-5', 'abc', '1e9'] as $bad) {
+            $out = $this->toolset->call('inventory_item_set', ['sku' => 'p', 'name' => 'P', 'price' => $bad], $rw, $this->ctx);
+            self::assertFalse($out['ok'], "price {$bad} must be rejected");
+            self::assertSame('invalid', $out['error']);
+        }
+        // And nothing was persisted from the failed writes.
+        $got = $this->toolset->call('inventory_item_get', ['sku' => 'p'], $rw, $this->ctx);
+        self::assertNull($got['item']);
+    }
+
+    public function test_a_content_token_cannot_write_an_item(): void
+    {
+        // The item write gates on inventory:write like every other write — an
+        // "all collections" token is not that capability, so the tool is invisible.
+        self::assertSame([], array_filter(
+            array_column($this->toolset->definitions($this->principal('*:write')), 'name'),
+            static fn (string $n): bool => $n === 'inventory_item_set',
+        ));
+
+        $this->expectException(McpError::class);
+        $this->toolset->call('inventory_item_set', ['sku' => 'x', 'name' => 'X'], $this->principal('*:write'), $this->ctx);
+    }
+
+    public function test_category_two_level_depth_is_enforced(): void
+    {
+        $write = $this->principal('nimbuscms.inventory:write');
+        $top   = $this->toolset->call('inventory_category_set', ['name' => 'Grocery'], $write, $this->ctx);
+        self::assertTrue($top['ok']);
+        $topId = $top['category']['id'];
+
+        $child = $this->toolset->call('inventory_category_set', ['name' => 'Fruit', 'parent_id' => $topId], $write, $this->ctx);
+        self::assertTrue($child['ok']);
+        $childId = $child['category']['id'];
+
+        // Nesting under a child (a third level) is refused.
+        $tooDeep = $this->toolset->call('inventory_category_set', ['name' => 'Bananas', 'parent_id' => $childId], $write, $this->ctx);
+        self::assertFalse($tooDeep['ok']);
+        self::assertSame('invalid', $tooDeep['error']);
+    }
 }
diff --git a/tests/PackageIntegrationTest.php b/tests/PackageIntegrationTest.php
index f646340..b2b67b0 100644
--- a/tests/PackageIntegrationTest.php
+++ b/tests/PackageIntegrationTest.php
@@ -98,7 +98,7 @@ public function test_discovery_registers_the_migration_capability_toolset_and_gu
         self::assertSame([], $diagnostics, 'a correctly installed package must load cleanly');
         self::assertSame([InventoryPlugin::ID => $this->manifest()['name']], $loader->registered());
 
-        self::assertSame(['nimbuscms.inventory:001_ledger', 'nimbuscms.inventory:002_reservations'], array_column($migrations->all(), 'name'), 'its ledger + reservation migrations');
+        self::assertSame(['nimbuscms.inventory:001_ledger', 'nimbuscms.inventory:002_reservations', 'nimbuscms.inventory:003_items'], array_column($migrations->all(), 'name'), 'its ledger + reservation + item-master migrations');
         self::assertSame([InventoryPlugin::ID], $capabilities->managementResources(), 'its grantable capability');
         self::assertCount(1, $mcpToolsets->all(), 'its MCP toolset');
         self::assertNotSame([], $skills->documents(), 'its agent guide');