docs: replace both AGENTS.md files with one CLAUDE.md

One agent doc per repo, and it is CLAUDE.md. This repo carried two --
one at the root and one under webber-api/ -- which is the drift problem
in its purest form: two documents, one subject, and no way to know which
the last reader trusted. Written fresh rather than reformatted.

README.md linked to webber-api/AGENTS.md, so that pointer moves with the
file rather than dangling.

The architecture section states the method used to establish what is
live -- import the app inside the container and read sys.modules -- and
then the case where that method fails here. src/domains/tools is absent
from a cold snapshot and is entirely live: each agent's _register_tools
imports its tool package from inside the method body, on every
/agents/run. Absence from a snapshot taken before any request is served
is a timing artifact, not evidence of death, and deleting on that basis
would have removed the tool layer.

Co-Authored-By: Claude <noreply@anthropic.com>

.claude/settings.json

@@ -0,0 +1,60 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pql)",
+      "Bash(pql *)",
+      "Bash(/home/jpmschweitzer/.local/bin/pql:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git branch:*)",
+      "Bash(.venv/bin/python -m pytest:*)",
+      "Bash(.venv/bin/pytest:*)",
+      "Bash(pytest:*)",
+      "Bash(ruff *)",
+      "Bash(mypy *)",
+      "Bash(docker logs webber:*)",
+      "Bash(curl -s http://localhost:8086/*)",
+      "Bash(curl -s http://localhost:8095/*)"
+    ],
+    "deny": [
+      "Bash(sudo *)",
+      "Bash(su *)",
+      "Bash(rm -rf /*)",
+      "Bash(rm -rf ~*)",
+      "Bash(rm -rf $HOME*)",
+      "Bash(mkfs*)",
+      "Bash(dd if=*)",
+      "Bash(chmod 777 *)",
+      "Bash(chmod -R 777 *)",
+      "Bash(find * -exec*)",
+      "Bash(find * -delete*)",
+      "Bash(git add -A*)",
+      "Bash(git * add -A*)",
+      "Bash(git add --all*)",
+      "Bash(git * add --all*)",
+      "Bash(git add .)",
+      "Bash(git * add .)",
+      "Bash(git push --force*)",
+      "Bash(git * push --force*)",
+      "Bash(git push -f*)",
+      "Bash(git * push -f*)",
+      "Bash(git reset --hard*)",
+      "Bash(git * reset --hard*)",
+      "Bash(git clean -fd*)",
+      "Bash(git * clean -fd*)",
+      "Bash(git clean -fdx*)",
+      "Bash(git * clean -fdx*)",
+      "Bash(git branch -D *)",
+      "Bash(git * branch -D *)",
+      "Bash(git checkout -- *)",
+      "Bash(git * checkout -- *)",
+      "Bash(git restore .*)",
+      "Bash(git * restore .*)",
+      "Bash(git commit --no-verify*)",
+      "Bash(git * commit --no-verify*)",
+      "Bash(git merge --no-ff*)",
+      "Bash(git * merge --no-ff*)"
+    ]
+  }
+}

.gitattributes

@@ -0,0 +1 @@
+.pql/changelog/*.sql merge=union

.gitignore

@@ -75,3 +75,8 @@ webber-sandbox/.current_template
 
 # Ruff cache
 .ruff_cache/
+
+# Claude Code user-specific settings
+.claude/settings.local.json
+.pql/*
+!.pql/changelog/

.pql/changelog/0000-format.sql

@@ -0,0 +1,11 @@
+-- Changelog format marker, written by pql. Comments only: this file
+-- is never executed — Import descends into the per-table directories
+-- and does not read the changelog root.
+--
+-- A changelog carrying no marker is format 1, the shape that existed
+-- before formats were versioned. An older format is migrated forward
+-- by `pql plan upgrade` (and automatically from the post-merge hook);
+-- a newer one is refused rather than replayed under rules this binary
+-- does not know. See D-28 and docs/versions.md.
+-- pql:changelog_format: 2.0.0
+-- pql:written_by: 2.2.0

.pql/changelog/ticket_deps/0000-schema.sql

@@ -0,0 +1,139 @@
+-- Auto-generated by pql init. CREATE TABLE statements
+-- for the planning schema; per-table dir keeps the changelog
+-- self-describing per D-15. CREATE TABLE IF NOT EXISTS is
+-- idempotent so running schema files from each directory in
+-- replay order is harmless.
+--
+-- Importer parses the markers below to detect schema drift
+-- between the producing pql version and the local one — a
+-- bumped canonical_version means projection rules changed
+-- and replay must refuse rather than silently corrupt state.
+-- pql:created_by: 2.2.0
+-- pql:canonical_version: 2
+
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id                TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('confirmed','question','rejected')),
+    domain            TEXT NOT NULL,
+    title             TEXT NOT NULL,
+    status            TEXT NOT NULL DEFAULT 'active'
+                          CHECK(status IN ('active','superseded','resolved','open')),
+    date              TEXT,
+    file_path         TEXT NOT NULL,
+    synced_at         TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS decision_refs (
+    source_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    target_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    ref_type          TEXT NOT NULL
+                          CHECK(ref_type IN ('supersedes','references','resolves','depends_on','amends')),
+    note              TEXT,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (source_id, target_id, ref_type)
+);
+
+-- Identity split (D-26): a ticket's stable, collision-proof identity is its
+-- record_id (a locally-generated ULID, planning.NewRecordID); the friendly
+-- T-NNN label lives in ticket_idmap and may be reconciled. Every structural
+-- reference (parent, deps, history, labels) targets record_id, so a label
+-- clash never corrupts the graph — only ticket_idmap needs a relabel.
+CREATE TABLE IF NOT EXISTS tickets (
+    record_id         TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('initiative','epic','story','task','bug')),
+    parent_record_id  TEXT REFERENCES tickets(record_id),
+    title             TEXT NOT NULL,
+    description       TEXT,
+    -- No CHECK enumeration: the ticket status vocabulary is per-vault
+    -- configurable (ticket_statuses in .pql/config.yaml). Validation lives
+    -- in Go (planning.StatusSet), so adding/renaming statuses needs no
+    -- schema change. The DEFAULT is a harmless fallback — CreateTicket
+    -- always inserts the configured default explicitly.
+    status            TEXT NOT NULL DEFAULT 'backlog',
+    priority          TEXT DEFAULT 'medium'
+                          CHECK(priority IN ('critical','high','medium','low')),
+    assigned_to       TEXT,
+    team              TEXT,
+    decision_ref      TEXT REFERENCES decisions(id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+-- ticket_idmap maps a record_id to its current friendly label (T-NNN).
+-- ticket_id is intentionally NOT globally unique: two uncoordinated clones
+-- can mint the same label, which surfaces as a duplicate-label collision
+-- (detected at replay) and is fixed with "pql ticket relabel".
+CREATE TABLE IF NOT EXISTS ticket_idmap (
+    record_id         TEXT PRIMARY KEY REFERENCES tickets(record_id),
+    ticket_id         TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_deps (
+    blocker_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    blocked_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (blocker_record_id, blocked_record_id)
+);
+
+CREATE TABLE IF NOT EXISTS ticket_history (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    field             TEXT NOT NULL,
+    old_value         TEXT,
+    new_value         TEXT,
+    changed_by        TEXT,
+    changed_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT UNIQUE,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_labels (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    label             TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (ticket_record_id, label)
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_tickets_status        ON tickets(status);
+CREATE INDEX IF NOT EXISTS idx_tickets_team          ON tickets(team);
+CREATE INDEX IF NOT EXISTS idx_tickets_decision_ref  ON tickets(decision_ref);
+CREATE INDEX IF NOT EXISTS idx_tickets_assigned      ON tickets(assigned_to);
+CREATE INDEX IF NOT EXISTS idx_tickets_parent        ON tickets(parent_record_id);
+CREATE INDEX IF NOT EXISTS idx_ticket_idmap_label    ON ticket_idmap(ticket_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_domain      ON decisions(domain);
+CREATE INDEX IF NOT EXISTS idx_decisions_type        ON decisions(type);
+CREATE INDEX IF NOT EXISTS idx_decision_refs_target  ON decision_refs(target_id);

.pql/changelog/ticket_history/0000-schema.sql

@@ -0,0 +1,139 @@
+-- Auto-generated by pql init. CREATE TABLE statements
+-- for the planning schema; per-table dir keeps the changelog
+-- self-describing per D-15. CREATE TABLE IF NOT EXISTS is
+-- idempotent so running schema files from each directory in
+-- replay order is harmless.
+--
+-- Importer parses the markers below to detect schema drift
+-- between the producing pql version and the local one — a
+-- bumped canonical_version means projection rules changed
+-- and replay must refuse rather than silently corrupt state.
+-- pql:created_by: 2.2.0
+-- pql:canonical_version: 2
+
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id                TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('confirmed','question','rejected')),
+    domain            TEXT NOT NULL,
+    title             TEXT NOT NULL,
+    status            TEXT NOT NULL DEFAULT 'active'
+                          CHECK(status IN ('active','superseded','resolved','open')),
+    date              TEXT,
+    file_path         TEXT NOT NULL,
+    synced_at         TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS decision_refs (
+    source_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    target_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    ref_type          TEXT NOT NULL
+                          CHECK(ref_type IN ('supersedes','references','resolves','depends_on','amends')),
+    note              TEXT,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (source_id, target_id, ref_type)
+);
+
+-- Identity split (D-26): a ticket's stable, collision-proof identity is its
+-- record_id (a locally-generated ULID, planning.NewRecordID); the friendly
+-- T-NNN label lives in ticket_idmap and may be reconciled. Every structural
+-- reference (parent, deps, history, labels) targets record_id, so a label
+-- clash never corrupts the graph — only ticket_idmap needs a relabel.
+CREATE TABLE IF NOT EXISTS tickets (
+    record_id         TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('initiative','epic','story','task','bug')),
+    parent_record_id  TEXT REFERENCES tickets(record_id),
+    title             TEXT NOT NULL,
+    description       TEXT,
+    -- No CHECK enumeration: the ticket status vocabulary is per-vault
+    -- configurable (ticket_statuses in .pql/config.yaml). Validation lives
+    -- in Go (planning.StatusSet), so adding/renaming statuses needs no
+    -- schema change. The DEFAULT is a harmless fallback — CreateTicket
+    -- always inserts the configured default explicitly.
+    status            TEXT NOT NULL DEFAULT 'backlog',
+    priority          TEXT DEFAULT 'medium'
+                          CHECK(priority IN ('critical','high','medium','low')),
+    assigned_to       TEXT,
+    team              TEXT,
+    decision_ref      TEXT REFERENCES decisions(id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+-- ticket_idmap maps a record_id to its current friendly label (T-NNN).
+-- ticket_id is intentionally NOT globally unique: two uncoordinated clones
+-- can mint the same label, which surfaces as a duplicate-label collision
+-- (detected at replay) and is fixed with "pql ticket relabel".
+CREATE TABLE IF NOT EXISTS ticket_idmap (
+    record_id         TEXT PRIMARY KEY REFERENCES tickets(record_id),
+    ticket_id         TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_deps (
+    blocker_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    blocked_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (blocker_record_id, blocked_record_id)
+);
+
+CREATE TABLE IF NOT EXISTS ticket_history (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    field             TEXT NOT NULL,
+    old_value         TEXT,
+    new_value         TEXT,
+    changed_by        TEXT,
+    changed_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT UNIQUE,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_labels (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    label             TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (ticket_record_id, label)
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_tickets_status        ON tickets(status);
+CREATE INDEX IF NOT EXISTS idx_tickets_team          ON tickets(team);
+CREATE INDEX IF NOT EXISTS idx_tickets_decision_ref  ON tickets(decision_ref);
+CREATE INDEX IF NOT EXISTS idx_tickets_assigned      ON tickets(assigned_to);
+CREATE INDEX IF NOT EXISTS idx_tickets_parent        ON tickets(parent_record_id);
+CREATE INDEX IF NOT EXISTS idx_ticket_idmap_label    ON ticket_idmap(ticket_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_domain      ON decisions(domain);
+CREATE INDEX IF NOT EXISTS idx_decisions_type        ON decisions(type);
+CREATE INDEX IF NOT EXISTS idx_decision_refs_target  ON decision_refs(target_id);

.pql/changelog/ticket_idmap/0000-schema.sql

@@ -0,0 +1,139 @@
+-- Auto-generated by pql init. CREATE TABLE statements
+-- for the planning schema; per-table dir keeps the changelog
+-- self-describing per D-15. CREATE TABLE IF NOT EXISTS is
+-- idempotent so running schema files from each directory in
+-- replay order is harmless.
+--
+-- Importer parses the markers below to detect schema drift
+-- between the producing pql version and the local one — a
+-- bumped canonical_version means projection rules changed
+-- and replay must refuse rather than silently corrupt state.
+-- pql:created_by: 2.2.0
+-- pql:canonical_version: 2
+
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id                TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('confirmed','question','rejected')),
+    domain            TEXT NOT NULL,
+    title             TEXT NOT NULL,
+    status            TEXT NOT NULL DEFAULT 'active'
+                          CHECK(status IN ('active','superseded','resolved','open')),
+    date              TEXT,
+    file_path         TEXT NOT NULL,
+    synced_at         TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS decision_refs (
+    source_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    target_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    ref_type          TEXT NOT NULL
+                          CHECK(ref_type IN ('supersedes','references','resolves','depends_on','amends')),
+    note              TEXT,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (source_id, target_id, ref_type)
+);
+
+-- Identity split (D-26): a ticket's stable, collision-proof identity is its
+-- record_id (a locally-generated ULID, planning.NewRecordID); the friendly
+-- T-NNN label lives in ticket_idmap and may be reconciled. Every structural
+-- reference (parent, deps, history, labels) targets record_id, so a label
+-- clash never corrupts the graph — only ticket_idmap needs a relabel.
+CREATE TABLE IF NOT EXISTS tickets (
+    record_id         TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('initiative','epic','story','task','bug')),
+    parent_record_id  TEXT REFERENCES tickets(record_id),
+    title             TEXT NOT NULL,
+    description       TEXT,
+    -- No CHECK enumeration: the ticket status vocabulary is per-vault
+    -- configurable (ticket_statuses in .pql/config.yaml). Validation lives
+    -- in Go (planning.StatusSet), so adding/renaming statuses needs no
+    -- schema change. The DEFAULT is a harmless fallback — CreateTicket
+    -- always inserts the configured default explicitly.
+    status            TEXT NOT NULL DEFAULT 'backlog',
+    priority          TEXT DEFAULT 'medium'
+                          CHECK(priority IN ('critical','high','medium','low')),
+    assigned_to       TEXT,
+    team              TEXT,
+    decision_ref      TEXT REFERENCES decisions(id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+-- ticket_idmap maps a record_id to its current friendly label (T-NNN).
+-- ticket_id is intentionally NOT globally unique: two uncoordinated clones
+-- can mint the same label, which surfaces as a duplicate-label collision
+-- (detected at replay) and is fixed with "pql ticket relabel".
+CREATE TABLE IF NOT EXISTS ticket_idmap (
+    record_id         TEXT PRIMARY KEY REFERENCES tickets(record_id),
+    ticket_id         TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_deps (
+    blocker_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    blocked_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (blocker_record_id, blocked_record_id)
+);
+
+CREATE TABLE IF NOT EXISTS ticket_history (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    field             TEXT NOT NULL,
+    old_value         TEXT,
+    new_value         TEXT,
+    changed_by        TEXT,
+    changed_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT UNIQUE,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_labels (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    label             TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (ticket_record_id, label)
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_tickets_status        ON tickets(status);
+CREATE INDEX IF NOT EXISTS idx_tickets_team          ON tickets(team);
+CREATE INDEX IF NOT EXISTS idx_tickets_decision_ref  ON tickets(decision_ref);
+CREATE INDEX IF NOT EXISTS idx_tickets_assigned      ON tickets(assigned_to);
+CREATE INDEX IF NOT EXISTS idx_tickets_parent        ON tickets(parent_record_id);
+CREATE INDEX IF NOT EXISTS idx_ticket_idmap_label    ON ticket_idmap(ticket_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_domain      ON decisions(domain);
+CREATE INDEX IF NOT EXISTS idx_decisions_type        ON decisions(type);
+CREATE INDEX IF NOT EXISTS idx_decision_refs_target  ON decision_refs(target_id);

.pql/changelog/ticket_labels/0000-schema.sql

@@ -0,0 +1,139 @@
+-- Auto-generated by pql init. CREATE TABLE statements
+-- for the planning schema; per-table dir keeps the changelog
+-- self-describing per D-15. CREATE TABLE IF NOT EXISTS is
+-- idempotent so running schema files from each directory in
+-- replay order is harmless.
+--
+-- Importer parses the markers below to detect schema drift
+-- between the producing pql version and the local one — a
+-- bumped canonical_version means projection rules changed
+-- and replay must refuse rather than silently corrupt state.
+-- pql:created_by: 2.2.0
+-- pql:canonical_version: 2
+
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id                TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('confirmed','question','rejected')),
+    domain            TEXT NOT NULL,
+    title             TEXT NOT NULL,
+    status            TEXT NOT NULL DEFAULT 'active'
+                          CHECK(status IN ('active','superseded','resolved','open')),
+    date              TEXT,
+    file_path         TEXT NOT NULL,
+    synced_at         TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS decision_refs (
+    source_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    target_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    ref_type          TEXT NOT NULL
+                          CHECK(ref_type IN ('supersedes','references','resolves','depends_on','amends')),
+    note              TEXT,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (source_id, target_id, ref_type)
+);
+
+-- Identity split (D-26): a ticket's stable, collision-proof identity is its
+-- record_id (a locally-generated ULID, planning.NewRecordID); the friendly
+-- T-NNN label lives in ticket_idmap and may be reconciled. Every structural
+-- reference (parent, deps, history, labels) targets record_id, so a label
+-- clash never corrupts the graph — only ticket_idmap needs a relabel.
+CREATE TABLE IF NOT EXISTS tickets (
+    record_id         TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('initiative','epic','story','task','bug')),
+    parent_record_id  TEXT REFERENCES tickets(record_id),
+    title             TEXT NOT NULL,
+    description       TEXT,
+    -- No CHECK enumeration: the ticket status vocabulary is per-vault
+    -- configurable (ticket_statuses in .pql/config.yaml). Validation lives
+    -- in Go (planning.StatusSet), so adding/renaming statuses needs no
+    -- schema change. The DEFAULT is a harmless fallback — CreateTicket
+    -- always inserts the configured default explicitly.
+    status            TEXT NOT NULL DEFAULT 'backlog',
+    priority          TEXT DEFAULT 'medium'
+                          CHECK(priority IN ('critical','high','medium','low')),
+    assigned_to       TEXT,
+    team              TEXT,
+    decision_ref      TEXT REFERENCES decisions(id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+-- ticket_idmap maps a record_id to its current friendly label (T-NNN).
+-- ticket_id is intentionally NOT globally unique: two uncoordinated clones
+-- can mint the same label, which surfaces as a duplicate-label collision
+-- (detected at replay) and is fixed with "pql ticket relabel".
+CREATE TABLE IF NOT EXISTS ticket_idmap (
+    record_id         TEXT PRIMARY KEY REFERENCES tickets(record_id),
+    ticket_id         TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_deps (
+    blocker_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    blocked_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (blocker_record_id, blocked_record_id)
+);
+
+CREATE TABLE IF NOT EXISTS ticket_history (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    field             TEXT NOT NULL,
+    old_value         TEXT,
+    new_value         TEXT,
+    changed_by        TEXT,
+    changed_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT UNIQUE,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_labels (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    label             TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (ticket_record_id, label)
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_tickets_status        ON tickets(status);
+CREATE INDEX IF NOT EXISTS idx_tickets_team          ON tickets(team);
+CREATE INDEX IF NOT EXISTS idx_tickets_decision_ref  ON tickets(decision_ref);
+CREATE INDEX IF NOT EXISTS idx_tickets_assigned      ON tickets(assigned_to);
+CREATE INDEX IF NOT EXISTS idx_tickets_parent        ON tickets(parent_record_id);
+CREATE INDEX IF NOT EXISTS idx_ticket_idmap_label    ON ticket_idmap(ticket_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_domain      ON decisions(domain);
+CREATE INDEX IF NOT EXISTS idx_decisions_type        ON decisions(type);
+CREATE INDEX IF NOT EXISTS idx_decision_refs_target  ON decision_refs(target_id);

.pql/changelog/tickets/0000-schema.sql

@@ -0,0 +1,139 @@
+-- Auto-generated by pql init. CREATE TABLE statements
+-- for the planning schema; per-table dir keeps the changelog
+-- self-describing per D-15. CREATE TABLE IF NOT EXISTS is
+-- idempotent so running schema files from each directory in
+-- replay order is harmless.
+--
+-- Importer parses the markers below to detect schema drift
+-- between the producing pql version and the local one — a
+-- bumped canonical_version means projection rules changed
+-- and replay must refuse rather than silently corrupt state.
+-- pql:created_by: 2.2.0
+-- pql:canonical_version: 2
+
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id                TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('confirmed','question','rejected')),
+    domain            TEXT NOT NULL,
+    title             TEXT NOT NULL,
+    status            TEXT NOT NULL DEFAULT 'active'
+                          CHECK(status IN ('active','superseded','resolved','open')),
+    date              TEXT,
+    file_path         TEXT NOT NULL,
+    synced_at         TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS decision_refs (
+    source_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    target_id         TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+    ref_type          TEXT NOT NULL
+                          CHECK(ref_type IN ('supersedes','references','resolves','depends_on','amends')),
+    note              TEXT,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (source_id, target_id, ref_type)
+);
+
+-- Identity split (D-26): a ticket's stable, collision-proof identity is its
+-- record_id (a locally-generated ULID, planning.NewRecordID); the friendly
+-- T-NNN label lives in ticket_idmap and may be reconciled. Every structural
+-- reference (parent, deps, history, labels) targets record_id, so a label
+-- clash never corrupts the graph — only ticket_idmap needs a relabel.
+CREATE TABLE IF NOT EXISTS tickets (
+    record_id         TEXT PRIMARY KEY,
+    type              TEXT NOT NULL CHECK(type IN ('initiative','epic','story','task','bug')),
+    parent_record_id  TEXT REFERENCES tickets(record_id),
+    title             TEXT NOT NULL,
+    description       TEXT,
+    -- No CHECK enumeration: the ticket status vocabulary is per-vault
+    -- configurable (ticket_statuses in .pql/config.yaml). Validation lives
+    -- in Go (planning.StatusSet), so adding/renaming statuses needs no
+    -- schema change. The DEFAULT is a harmless fallback — CreateTicket
+    -- always inserts the configured default explicitly.
+    status            TEXT NOT NULL DEFAULT 'backlog',
+    priority          TEXT DEFAULT 'medium'
+                          CHECK(priority IN ('critical','high','medium','low')),
+    assigned_to       TEXT,
+    team              TEXT,
+    decision_ref      TEXT REFERENCES decisions(id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+-- ticket_idmap maps a record_id to its current friendly label (T-NNN).
+-- ticket_id is intentionally NOT globally unique: two uncoordinated clones
+-- can mint the same label, which surfaces as a duplicate-label collision
+-- (detected at replay) and is fixed with "pql ticket relabel".
+CREATE TABLE IF NOT EXISTS ticket_idmap (
+    record_id         TEXT PRIMARY KEY REFERENCES tickets(record_id),
+    ticket_id         TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_deps (
+    blocker_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    blocked_record_id TEXT NOT NULL REFERENCES tickets(record_id),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (blocker_record_id, blocked_record_id)
+);
+
+CREATE TABLE IF NOT EXISTS ticket_history (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    field             TEXT NOT NULL,
+    old_value         TEXT,
+    new_value         TEXT,
+    changed_by        TEXT,
+    changed_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT UNIQUE,
+    canonical_version INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS ticket_labels (
+    ticket_record_id  TEXT NOT NULL REFERENCES tickets(record_id),
+    label             TEXT NOT NULL,
+    created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at        TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at        TEXT,
+    hash              TEXT,
+    canonical_version INTEGER,
+    PRIMARY KEY (ticket_record_id, label)
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_tickets_status        ON tickets(status);
+CREATE INDEX IF NOT EXISTS idx_tickets_team          ON tickets(team);
+CREATE INDEX IF NOT EXISTS idx_tickets_decision_ref  ON tickets(decision_ref);
+CREATE INDEX IF NOT EXISTS idx_tickets_assigned      ON tickets(assigned_to);
+CREATE INDEX IF NOT EXISTS idx_tickets_parent        ON tickets(parent_record_id);
+CREATE INDEX IF NOT EXISTS idx_ticket_idmap_label    ON ticket_idmap(ticket_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_domain      ON decisions(domain);
+CREATE INDEX IF NOT EXISTS idx_decisions_type        ON decisions(type);
+CREATE INDEX IF NOT EXISTS idx_decision_refs_target  ON decision_refs(target_id);

AGENTS.md

@@ -1,289 +0,0 @@
-# Webber Monorepo - Agent Instructions
-
-> **Start every session by reading this file.**
-> This file contains everything you need to work with this codebase efficiently.
-
-## Quick Reference
-
-| Action | Command |
-|--------|---------|
-| Start API server | `cd webber-api && ./wakeup.sh` |
-| View API logs | `tail -f webber-api/logs/server.log` |
-| Run API tests | `cd webber-api && .venv/bin/python -m pytest tests/ -v` |
-| Check CLI status | `cd webber-cli && .venv/bin/webber-cli status` |
-| Load sandbox | `./sandbox.sh load calculator-cli` |
-| Explore sandbox | `cd webber-cli && .venv/bin/webber-cli explore "query" -d ../webber-sandbox` |
-
----
-
-## Repository Structure
-
-```
-webber/
-├── webber-api/          # FastAPI backend server
-│   ├── src/             # API source code
-│   ├── tests/           # API tests (pytest)
-│   ├── docs/            # Architecture docs, COVERAGE.md
-│   ├── logs/            # Runtime logs (server.log)
-│   ├── .venv/           # API virtual environment
-│   ├── wakeup.sh        # Dev server startup script
-│   └── AGENTS.md        # API-specific development guide
-│
-├── webber-cli/          # CLI client
-│   ├── webber_cli/      # Python package (underscore!)
-│   ├── .venv/           # CLI virtual environment
-│   └── README.md        # CLI usage guide
-│
-├── webber-sandbox/      # Active test project (contents swappable)
-│   ├── src/             # Current project source
-│   ├── tests/           # Current project tests
-│   ├── .venv/           # Sandbox virtual environment
-│   └── TASKS.md         # Tasks for Webber to complete
-│
-├── sandbox-templates/   # Template storage
-│   ├── calculator-cli/  # Simple CLI with intentional bugs
-│   └── empty/           # Blank starter project
-│
-├── sandbox.sh           # Sandbox management script
-└── AGENTS.md            # THIS FILE
-```
-
----
-
-## Development Workflow
-
-### 1. Start the API Server
-
-```bash
-cd webber-api
-./wakeup.sh
-```
-
-- **Port:** 8095 (dev), 8086 (production Docker)
-- **Logs:** `webber-api/logs/server.log`
-- **Health check:** `curl http://localhost:8095/health`
-- **API docs:** http://localhost:8095/docs
-
-To stop: `Ctrl+C` or `pkill -f "uvicorn src.main:app"`
-
-### 2. Run Tests
-
-```bash
-# API tests (39 tests)
-cd webber-api
-.venv/bin/python -m pytest tests/ -v
-
-# With coverage
-.venv/bin/python -m pytest tests/ --cov=src
-
-# Single test file
-.venv/bin/python -m pytest tests/test_tools.py -v
-```
-
-### 3. Use the CLI
-
-```bash
-cd webber-cli
-
-# Check API connection
-.venv/bin/webber-cli status
-
-# Interactive chat (default mode - full capabilities)
-.venv/bin/webber-cli chat -d ../webber-sandbox
-
-# Read-only mode (safe exploration and planning)
-.venv/bin/webber-cli chat --mode plan -d ../webber-sandbox
-
-# Auto-accept mode (no approval prompts - use with caution)
-.venv/bin/webber-cli chat --mode auto_accept -d ../webber-sandbox
-
-# List previous sessions
-.venv/bin/webber-cli sessions
-
-# Resume a previous session
-.venv/bin/webber-cli chat --resume <session-id>
-```
-
-**CLI Features:**
-- **Tab completion** for commands and file paths
-- **Command history** persisted to `~/.webber_history`
-- **Session persistence** - conversations saved and resumable
-- **Config file** - persistent settings via `~/.webber/config.toml`
-- **Runtime mode switching** via `mode plan|default|auto_accept`
-- **Directory navigation** via `cd <path>`
-
-**Configuration:**
-```bash
-# Show current config
-.venv/bin/webber-cli config
-
-# Initialize config file with defaults
-.venv/bin/webber-cli config --init
-```
-
-**Note:** The API server must be running for CLI commands to work.
-
----
-
-## Sandbox Management
-
-The sandbox is a swappable test project for functional testing.
-
-### Available Templates
-
-| Template | Description |
-|----------|-------------|
-| `calculator-cli` | Python CLI with intentional bugs (div-by-zero, missing tests) |
-| `empty` | Blank starter project |
-
-### Commands
-
-```bash
-# List available templates
-./sandbox.sh list
-
-# Load a template (clears sandbox, preserves .venv)
-./sandbox.sh load calculator-cli
-
-# Reset to last loaded template
-./sandbox.sh reset
-
-# Save current sandbox as new template
-./sandbox.sh save my-template
-
-# Check current status
-./sandbox.sh status
-```
-
-### After Loading a Template
-
-```bash
-cd webber-sandbox
-source .venv/bin/activate  # Create .venv first if missing
-pip install -r requirements.txt
-
-# Read the tasks
-cat TASKS.md
-
-# Run the project's tests
-pytest tests/ -v
-```
-
----
-
-## Testing Webber's Capabilities
-
-### Scenario: Find bugs in calculator-cli
-
-```bash
-# 1. Load the template
-./sandbox.sh load calculator-cli
-
-# 2. Have Webber explore it (plan mode = read-only)
-cd webber-cli
-.venv/bin/webber-cli chat --mode plan -d ../webber-sandbox
-# Then ask: "find all bugs in the code"
-
-# 3. Check TASKS.md for expected bugs
-cat ../webber-sandbox/TASKS.md
-```
-
-### Known bugs in calculator-cli:
-- Division by zero not handled (`operations.py:divide`)
-- Invalid operation causes KeyError (`main.py:get_operation`)
-- Power function broken for fractional exponents
-- Missing tests for divide and power functions
-
----
-
-## Key Files for Debugging
-
-| File | Purpose |
-|------|---------|
-| `webber-api/logs/server.log` | API server logs |
-| `webber-api/src/domains/agents/explore/prompts.py` | Explore agent system prompts |
-| `webber-api/src/domains/agents/explore/agent.py` | Explore agent implementation |
-| `webber-api/src/ollama/provider.py` | Ollama integration (sanitizes content:null) |
-| `webber-api/docs/COVERAGE.md` | Feature coverage and known issues |
-
----
-
-## Versioning & Releases
-
-Uses prefixed tags:
-- `api/vX.Y.Z` → Triggers API Docker build
-- `cli/vX.Y.Z` → Triggers CLI build (future)
-
-### MANDATORY Release Procedure
-
-**NEVER push a tag before updating version files.** Follow this exact order:
-
-```bash
-# For API releases:
-# 1. Update version in webber-api/pyproject.toml
-# 2. Update webber-api/CHANGELOG.md with release notes
-# 3. Commit the version bump
-git add -A && git commit -m "chore: release api vX.Y.Z"
-# 4. Create the tag (AFTER the commit)
-git tag api/vX.Y.Z
-# 5. Push everything together
-git push origin main --tags
-
-# For CLI releases:
-# 1. Update version in webber-cli/pyproject.toml
-# 2. Update webber-cli/CHANGELOG.md with release notes
-# 3. Commit the version bump
-git add -A && git commit -m "chore: release cli vX.Y.Z"
-# 4. Create the tag (AFTER the commit)
-git tag cli/vX.Y.Z
-# 5. Push everything together
-git push origin main --tags
-```
-
-**Why this matters:** Pushing a tag before the version commit requires deleting and recreating the tag, which can trigger CI/CD pipelines prematurely and cause deployment issues.
-
----
-
-## Troubleshooting
-
-### API server won't start
-```bash
-# Check if port is in use
-lsof -i :8095
-
-# Kill stuck process
-pkill -f "uvicorn src.main:app"
-```
-
-### CLI can't connect
-```bash
-# Check API is running
-curl http://localhost:8095/health
-
-# Check CLI config
-echo $WEBBER_API_URL  # Should be http://localhost:8095
-```
-
-### Ollama errors
-```bash
-# Check Ollama is running
-curl http://192.168.86.149:11434/api/tags
-
-# Check model is available
-curl http://192.168.86.149:11434/api/tags | grep mistral-nemo
-```
-
-### Tests failing
-```bash
-# Run with verbose output
-cd webber-api
-.venv/bin/python -m pytest tests/ -v --tb=short
-```
-
----
-
-## Known Limitations
-
-1. **Model hallucination** - Mistral Nemo sometimes makes up file contents instead of using tool results
-
-See `webber-api/docs/COVERAGE.md` for full feature coverage status.

CLAUDE.md

@@ -0,0 +1,182 @@
+# CLAUDE.md — webber
+
+Local-LLM multi-agent development assistant — "similar to Claude Code but running locally"
+(`webber-api/docs/architecture.md`), backed by Ollama via PydanticAI. Logical monorepo, single
+`.git`, three subprojects: `webber-api/` (FastAPI server, deployed), `webber-cli/` (Typer CLI
+client), `webber-sandbox/` (swappable test project used by `sandbox.sh`, not shipped).
+
+## Ports
+
+| | Port | How |
+|---|---|---|
+| Local dev | **8095** | `cd webber-api && ./wakeup.sh`, uvicorn `--reload`, logs to `webber-api/logs/server.log` |
+| Production | **8086** | container `webber`, confirmed running (`docker ps`) on `docker-dataplane` |
+
+`wakeup.sh` refuses to start if 8095 is already bound — it does not silently pick another
+port. Testing `localhost:8086` on the dev box hits the *container*, not your reload server.
+
+## Live contract
+
+`http://localhost:8086/openapi.json` — 10 paths, `version: 1.0.1` (verified 2026-08-09,
+matches `webber-api/pyproject.toml` and the live `/health` response). Human docs at
+`http://localhost:8086/docs`. Query the live spec rather than inferring routes from source —
+`src/domains/router.py` currently has two routers commented out (see Architecture), so a
+source read alone will overcount if you don't check whether an include is live.
+
+```
+/, /health, /agents/, /agents/run, /agents/stream, /agents/{agent_type},
+/conversations/, /conversations/{conversation_id},
+/conversations/{conversation_id}/messages, /conversations/{conversation_id}/save
+```
+
+## Architecture
+
+Domain-first layout under `webber-api/src/domains/<name>/`. `src/main.py` includes exactly one
+router, `src.domains.router.root_router`, which composes the domain routers. A full directory
+map lives in `webber-api/docs/architecture.md` — read that before adding a domain rather than
+duplicating it here.
+
+**How liveness below was established:** `docker exec webber python3 -c "import src.main; import
+sys; print(sorted(m for m in sys.modules if m.startswith('src.')))"` — i.e. importing the real
+app inside the running container and reading `sys.modules`, not grepping `main.py`. Re-run that
+command to re-check; a grep of imports will miss function-body imports, and this repo has one
+that matters.
+
+- **Wired at startup, serving routes:** `src.domains.health`, `src.domains.agents` (router +
+  `explore`/`plan`/`task` agent packages), `src.domains.conversations`, `src.shared.*`,
+  `src.ollama`, `src.db` (imported both by `conversations/router.py` at module scope and by
+  `main.py`'s lifespan shutdown handler).
+- **Present in source, explicitly disabled:** `src/domains/router.py` has
+  `# from src.domains.auth.router import router as auth_router` and the equivalent for
+  `tools_router` — both commented out with the include calls also commented out. `src/domains/auth/`
+  is just an empty `__init__.py`. This one *is* dead — the disabling is visible in the same file,
+  not a matter of tracing an indirect import.
+- **The trap: `src/domains/tools/` is not in `sys.modules` right after `import src.main`, but it
+  is not dead.** `src/domains/agents/{explore,plan,task}/agent.py` each have a method
+  (e.g. `PlanAgent._register_tools`) that does `from src.domains.agents.plan.tools import
+  register_plan_tools` **inside the function body**, called every time that agent is
+  constructed — i.e. on every `/agents/run` or `/agents/stream` request for that agent type.
+  That nested module then imports the real tool classes from `src.domains.tools.file`,
+  `.search`, `.shell` at module scope. A static snapshot taken before any request is served
+  will not show `src.domains.tools` loaded; that is a timing artifact, not evidence it is
+  unused. Don't delete `src/domains/tools/` on the strength of a `sys.modules` check alone —
+  confirm by hitting `/agents/run` and re-checking, or by tracing the call graph from each
+  agent's `_register_tools`.
+- **`src/cli/`** is the implementation behind `webber-cli`'s `pyproject.toml` script entry —
+  it is a separate Typer app, not imported by the API (`src.main`) at all. Its liveness is
+  "is the CLI installed and invoked", not "is it wired into the API process".
+
+Group new work by domain, not file type — `webber-api/docs/fastapi-best-practices.md` is the
+house reference (mirrors the convention used across the other in-house FastAPI services here).
+
+## Database
+
+SQLite by default (`database_url = "sqlite+aiosqlite:///./webber.db"` in
+`src/shared/config.py`), not Postgres — confirmed by reading `src/shared/config.py` and
+`src/db/database.py` (the latter's docstring says the pattern is ported from core-api, but
+the backend differs). Models under `webber-api/src/domains/<name>/models.py` import `Base`
+from `src/db/models.py`. No Alembic here (unlike core-api) — did not find a migrations
+directory; unverified whether schema changes have any managed migration path at all. Check
+before assuming one exists.
+
+## Working here
+
+**Test locally first.** `cd webber-api && ./wakeup.sh` auto-reloads on code changes (not on
+`requirements.txt` changes — restart after adding a dependency). Deploy only once a feature
+is complete and tested.
+
+```bash
+cd webber-api
+.venv/bin/python -m pytest tests/           # all tests
+.venv/bin/python -m pytest tests/ -v --cov  # verbose + coverage
+.venv/bin/python -m pytest tests/test_tools.py -v   # single file
+```
+
+`webber-api/pyproject.toml` declares `[tool.ruff]` and `[tool.mypy]` — unlike core-api, this
+repo does have ruff/mypy config; whether either runs in CI is a separate question (see CI below
+— it does not).
+
+Copy `webber-api/.env.example` to `webber-api/.env`. Notable defaults: `OLLAMA_URL` points at
+`192.168.86.149:11434` (the host's Ollama, not a container), `OLLAMA_AGENT_MODEL=gemma4:e2b`,
+optional Tatlock integration via `TATLOCK_API_URL`/`INTERNAL_API_KEY`, optional SearXNG via
+`SEARXNG_URL` for the `web_search` tool.
+
+### Sandbox
+
+`webber-sandbox/` is a disposable project used to exercise the agents end-to-end, managed by
+`./sandbox.sh {list,load,reset,save,status}` from the repo root. `sandbox-templates/` holds the
+reusable templates (`calculator-cli` has intentionally-seeded bugs for testing Explore/Task).
+This directory is fixture material, not shipped code — do not treat bugs in it as real bugs.
+
+### CLI
+
+`webber-cli/` is a Typer client (`webber-cli status|chat|explore|sessions|config`) with tab
+completion, session persistence (`~/.webber_history`, `~/.webber/config.toml`), and three chat
+modes (`plan` read-only, `default`, `auto_accept`). It talks to the API over HTTP — it does not
+share a process with `webber-api`. Run it from its own venv: `cd webber-cli && .venv/bin/webber-cli status`.
+
+## CI
+
+`.gitea/workflows/build-api.yml` triggers only on `api/vX.Y.Z` tags: creates a Gitea release,
+builds/pushes `git.schweitz.net/jpmschweitzer/webber-api`, then pings Watchtower.
+`build-cli.yml` triggers on `cli/vX.Y.Z` tags but is a placeholder — it only echoes a TODO, it
+does not build or publish anything. **No test or lint gate runs in CI for either package** —
+pytest and ruff only run locally or on request. Verify tests pass before tagging.
+
+## Work tracking
+
+Work lives in **pql**, not a markdown TODO or `docs/COVERAGE.md`. Tickets *and* decisions for
+this repo live in the **workspace** vault; this repo's `.pql/` and `governance/` trees stay
+empty (D-15).
+
+Two things must be spelled out on every invocation from in here, and each fails differently:
+
+- **`pql` is not on the non-interactive `PATH`** — use `/home/jpmschweitzer/.local/bin/pql`.
+- **`--vault /mnt/media/Projects` is mandatory.** pql anchors a vault at the nearest `.git/`
+  ancestor, and this repo is one, so a bare call resolves to *this repo's* empty vault. Reads
+  return nothing; a **write** creates a stray vault and starts ticket ids at T-1, colliding
+  with the real ones.
+
+```bash
+/home/jpmschweitzer/.local/bin/pql --vault /mnt/media/Projects ticket list
+/home/jpmschweitzer/.local/bin/pql --vault /mnt/media/Projects plan whatsnext
+/home/jpmschweitzer/.local/bin/pql --vault /mnt/media/Projects decisions list --domain webber
+```
+
+Do not add a TODO section to a markdown file.
+
+## Git
+
+- **History is linear — no merge commits.** Work on `main`, or a short-lived branch that is
+  fast-forwarded and deleted. (This repo's `AGENTS.md` previously mandated `feature/...` or
+  `fix/...` branches for every change and forbade committing to `main` directly — that rule was
+  retired workspace-wide on 2026-08-08 and does not apply here anymore.)
+- **Conventional Commits**: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`.
+- **Atomic commits** — one logical change each.
+- **Stage explicitly. Never `git add -A`** — denied by policy; it sweeps in whatever else is
+  dirty, including secrets.
+- Each package versions independently via prefixed tags (`api/vX.Y.Z`, `cli/vX.Y.Z`) and its
+  own `CHANGELOG.md` (`webber-api/CHANGELOG.md`, `webber-cli/CHANGELOG.md`); the root
+  `CHANGELOG.md` is just an index pointing at both.
+
+## Releasing (API)
+
+Ask whether a deploy is wanted first — it is not automatic.
+
+1. Bump the version in `webber-api/pyproject.toml`.
+2. Move `[Unreleased]` entries into a dated version section in `webber-api/CHANGELOG.md`.
+3. Stage the changed files by name, commit, tag `api/vX.Y.Z`, `git push origin main --tags`.
+4. Gitea CI (`build-api.yml`) builds and pushes the image on the tag; Watchtower deploys it.
+5. Verify: `curl http://192.168.86.149:8086/health`.
+
+CLI releases (`cli/vX.Y.Z`) currently only log a TODO in CI — there is no build/publish step
+to trigger yet.
+
+## Known issues (carried over, unverified beyond what's stated)
+
+- **Model hallucination**: the Explore agent's model can hallucinate file contents instead of
+  using actual tool results, per `webber-api/AGENTS.md` — a mitigation (stronger model or
+  response validation) was suggested there but not confirmed implemented.
+- **Ollama `content: null` workaround**: `src/ollama/provider.py` (confirmed present, loaded at
+  startup per the `sys.modules` check above) sanitizes `content: null` to `content: ""` for
+  assistant messages with tool calls, working around an Ollama API limitation.

README.md

@@ -107,13 +107,13 @@ This project uses prefixed tags for independent release cycles:
 ## Requirements
 
 - Python 3.12+
-- Ollama running with `mistral-nemo:latest` model
+- Ollama running with `gemma4:e2b` model
 - Docker (for production deployment)
 - SearXNG (optional, for web search)
 
 ## Documentation
 
-- `webber-api/AGENTS.md` - API development guidelines
+- `CLAUDE.md` - Agent development guidelines (repo-wide)
 - `webber-api/docs/COVERAGE.md` - Feature coverage and roadmap
 - `webber-api/docs/architecture.md` - System architecture
 - `webber-cli/README.md` - CLI usage guide

governance/README.md

@@ -0,0 +1,54 @@
+# Decisions, Questions, Rejected
+
+This directory holds structured planning records that pql parses
+into pql.db. Each record is a `### [DQR]-N: Title` heading inside
+a markdown file. Files live in three per-type subdirectories:
+
+- `decisions/<domain>.md` — confirmed design decisions
+- `questions/<domain>.md` — open questions that may resolve into
+  decisions or rejected proposals
+- `rejected/<domain>.md` — rejected proposals (kept for the audit
+  trail)
+
+The parser infers domain from the filename stem and record type
+from the parent subdirectory.
+
+D-records that propose implementation work link to `initiative`-type
+tickets via `decision_ref`. Run `pql decisions show <id>
+--with-tickets` to inspect implementation status.
+
+## Recommended domains
+
+Start with this canonical set; create files as records land in
+each domain:
+
+- **architecture** — structural commitments (storage, layering,
+  languages, libraries)
+- **process** — team workflow (commits, branches, releases, reviews)
+- **design** — user-facing surface (UX, UI, public APIs)
+- **coding-conventions** — team-internal code shape (style, lint,
+  file layout)
+- **testing** — quality strategy (coverage, layers, gates)
+
+You might also want, project-permitting:
+
+- `accessibility` — if you ship user-facing software
+- `security` — if you handle user data or network surfaces
+- `licensing` — if you release open-source or commercial
+- `documentation` — if user-docs are non-trivial
+- `deployment` — if shipping is non-trivial
+- `performance` — if you have perf budgets / SLOs
+
+<!-- pql:records (auto-generated; do not edit manually) -->
+
+## Decisions
+
+- _(none)_
+
+## Open questions
+
+- _(none)_
+
+## Rejected
+
+- _(none)_

webber-api/.env.example

@@ -14,7 +14,7 @@ CORS_ORIGINS=["http://localhost:3000","http://localhost:8080"]
 
 # LLM - Ollama (tower-of-joy)
 OLLAMA_URL=http://192.168.86.149:11434
-OLLAMA_AGENT_MODEL=mistral-nemo-large:latest
+OLLAMA_AGENT_MODEL=gemma4:e2b
 OLLAMA_EMBED_MODEL=nomic-embed-text:latest
 
 # Auth - Tatlock integration (optional)

webber-api/AGENTS.md

@@ -1,128 +0,0 @@
-
-# AGENTS.md
-
-> **Start every session by reading this file.**
-> This file outlines the operational protocols, coding standards, and architectural decisions for this FastAPI project.
-
-## 1. Agent Operational Protocols
-
-### 🧠 Work Patterns (Plan-Act-Reflect)
-* **Plan:** Before writing code, briefly outline your plan. Identify which files you will touch and what the side effects might be.
-* **Act:** Execute the changes in small, atomic steps.
-* **Reflect:** After coding, verify your work. Did you break existing tests? Did you add new tests?
-
-### 🛡️ Git Discipline
-* **ALWAYS add the relevant tests for the added code** Make sure to keep the test coverage up as we go, and run tests before commiting.
-* **NEVER commit to `main` or `master` directly.** Always create a feature branch: `feature/your-feature-name` or `fix/issue-description`.
-* **Commit Messages:** Use the [Conventional Commits](https://www.conventionalcommits.org/) format.
-    * `feat: add user login endpoint`
-    * `fix: resolve database connection timeout`
-    * `refactor: split monolith dependency file`
-* **Atomic Commits:** Keep commits small. One logical change = one commit.
-
-### 📝 Changelog Maintenance
-* **Update `CHANGELOG.md`** with every user-facing change.
-* Format: `## [Unreleased] - YYYY-MM-DD` followed by `### Added`, `### Changed`, or `### Fixed`.
-
-### 🚀 Release Flow
-When changes are ready for deployment:
-
-1. **Ask user if deploy cycle is desired **
-
-2. **Update version** in `pyproject.toml`:
-   - Bug fixes: bump patch version (1.8.3 → 1.8.4)
-   - New features: bump minor version (1.8.4 → 1.9.0)
-
-3. **Update CHANGELOG.md**:
-   - Move items from `[Unreleased]` to new version section
-   - Add release date: `## [1.8.4] - 2025-12-16`
-
-4. **Commit and tag**:
-   ```bash
-   git add -A
-   git commit -m "fix: description of changes"
-   git tag v1.8.4
-   git push origin main --tags
-   ```
-
-5. **CI/CD triggers automatically**:
-   - Gitea CI builds Docker image on new version tag (starts with "v")
-   - Watchtower pulls and deploys to production
-   - Verify deployment: `curl http://192.168.86.149:8086/health`
-
----
-
-### 🧪 Local Development Setup
-
-* **Always test locally first** before committing and deploying. The build-deploy loop is slow.
-* **Only deploy** when a phase or feature is complete and tested locally
-* **Environment**: Copy `.env.example` to `.env` and configure for your local setup
-
-#### ⚠️ CRITICAL: Starting the Local Server
-
-**ALWAYS use `./wakeup.sh` to start the local server. NEVER use raw uvicorn commands.**
-
-```bash
-./wakeup.sh
-```
-
-The wakeup script provides:
-- **Port conflict detection** - Warns if port 8086 is already in use
-- **Virtual environment activation** - Ensures correct Python environment
-- **Centralized logging** - All logs written to `logs/server.log` for easy tailing
-- **Auto-reload** - Code changes picked up automatically (except requirements.txt changes)
-- **Consistent configuration** - Same startup every time
-
-To monitor logs in another terminal:
-```bash
-tail -f logs/server.log
-```
-
-To stop the server: Press `Ctrl+C`
-
-To kill a stuck server:
-```bash
-pkill -f "uvicorn src.main:app"
-# or
-kill $(lsof -t -i:8086)
-```
-
-#### Testing
-
-**Test REST endpoints** against `http://localhost:8086`:
-```bash
-curl http://localhost:8086/health
-curl http://localhost:8086/
-curl http://localhost:8086/docs   # Swagger UI
-```
-
-**Running tests**: Always use the venv explicitly to avoid environment mismatches:
-```bash
-.venv/bin/python -m pytest tests/           # All tests
-.venv/bin/python -m pytest tests/ -v        # Verbose output
-.venv/bin/python -m pytest tests/ --cov     # With coverage
-```
-
----
-
-## 1.5 Known Issues & Future Improvements
-
-### Explore Agent
-
-- **Model Hallucination**: Mistral Nemo sometimes hallucinates file contents instead of using actual tool results. Consider using a more capable model (codestral, qwen2.5-coder) or adding response validation.
-
-- **Ollama Provider**: We use a custom `WebberOllamaProvider` (ported from tatlock) that sanitizes `content: null` to `content: ""` for assistant messages with tool calls. This works around an Ollama API limitation.
-
-- **Gitignore Support**: ✅ Fixed - The filesystem tools now honor `.gitignore` patterns and default ignores (`.venv/`, `__pycache__/`, `node_modules/`, etc.).
-
----
-
-## 2. FastAPI Architecture & Best Practices
-*Reference: [FastAPI Best Practices](https://github.com/zhanymkanov/fastapi-best-practices)*
-
-### 📂 Project Structure (Directory-based, NOT File-type based)
-Do **not** group files by type (e.g., one huge `routers` folder). Group by **domain/module** inside a `src/` directory.
-
-**Correct Structure:**
-```text
-to be determined

webber-api/CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- Default `OLLAMA_AGENT_MODEL` is now `gemma4:e2b` instead of `mistral-nemo-large:latest`, so a deployment without an explicit override no longer exhausts shared GPU memory
+
 ## [1.0.1] - 2026-07-19
 
 ### Changed

webber-api/docs/architecture.md

@@ -13,7 +13,7 @@ Webber is a FastAPI-based agent orchestration service that provides:
 **Port:** 8086
 **Runtime:** Python 3.12, FastAPI, Uvicorn
 **Agent Framework:** PydanticAI
-**Default LLM:** Ollama with mistral-nemo-large:latest
+**Default LLM:** Ollama with gemma4:e2b
 
 ---
 
@@ -205,7 +205,7 @@ All settings via environment variables or `.env`:
 | HOST | 0.0.0.0 | Server host |
 | PORT | 8086 | Server port |
 | OLLAMA_URL | http://192.168.86.149:11434 | Ollama API URL |
-| OLLAMA_AGENT_MODEL | mistral-nemo-large:latest | Agent reasoning model |
+| OLLAMA_AGENT_MODEL | gemma4:e2b | Agent reasoning model |
 | OLLAMA_EMBED_MODEL | nomic-embed-text:latest | Embedding model |
 | TATLOCK_API_URL | http://tatlock:8000 | Tatlock auth service |
 | SEARXNG_URL | http://searxng:8080 | SearXNG web search instance |
@@ -359,7 +359,7 @@ Gitea Actions workflow:
 
 Deployed in Portainer `agents` stack alongside Tatlock:
 - Network: `docker-dataplane`
-- Registry: `git.schweitz.internal/jpmschweitzer/webber`
+- Registry: `git.schweitz.net/jpmschweitzer/webber`
 - Auto-update: Watchtower with label `com.centurylinklabs.watchtower.enable=true`
 
 ---

webber-api/src/shared/config.py

@@ -64,7 +64,7 @@ class Settings(BaseSettings):
 
     # LLM - Ollama (always hot in VRAM on tower-of-joy)
     ollama_url: str = "http://192.168.86.149:11434"
-    ollama_agent_model: str = "mistral-nemo-large:latest"
+    ollama_agent_model: str = "gemma4:e2b"
     ollama_embed_model: str = "nomic-embed-text:latest"
 
     # Auth - Tatlock integration