projax/docs/design.md

projax — PRD

Status: v1 draft, 2026-05-15 Authors: m, head (dialogue) Scope: Phase-1 build sufficient to live with the system; phases 2–3 listed but deferred.

1. Purpose

projax is m's personal data backbone for self-management — areas of life, projects within them, and aggregated views over tasks that live elsewhere. It subsumes (over time) the scattered state currently held in mai.projects, CalDAV task lists, Gitea issues, and mBrian topic hubs. No interface is canonical; each is a view.

Meta-requirement: flexibility. m's self-model evolves. Identity is by UUID; everything human-readable is renameable. The data model leans on jsonb + array-typed kinds so future re-categorization doesn't require a migration.

2. Model

2.1 Items in a DAG

Phase 1.5 collapsed the area/project structural distinction. Every node is an item; the kind array is kept for forward-compatibility (future: milestone, event, person, …) but area is no longer a special value. The seven seeded roots are just items with parent_ids = '{}'.

The hierarchy is a directed acyclic graph, not a tree: each item has zero or more parents, and the same item can surface under multiple branches. work.paliad and dev.paliad resolve to the same row. PER citations can use any valid path.

• Item — a node in the DAG. Examples: dev, home.spring-clean, work.paliad, paliad.note. The kind column carries ['project'] today; we may layer other types as needs arise.
• Task — atomic work item. Lives outside projax (CalDAV todos, Gitea issues, mai.tasks). projax references and aggregates them; it does not own them.

Structural rules:

• No cycles (enforced by items_before_write + compute_item_paths recursive-CTE ancestor closure).
• An item's slug must be unique among its siblings under any common parent (enforced by items_check_slug_collision BEFORE trigger, with the partial unique index items_root_slug_uniq covering the root case).
• Soft delete via deleted_at. Hard delete cascades through items_after_delete, which scrubs the deleted id from every descendant's parent_ids array.

2.2 Identity & naming

• id uuid — canonical, immutable.
• slug text — local-only segment (no dots). Renameable freely. Examples: prjx, spring-clean. Multi-word leaves use kebab-case.
• parent_ids uuid[] — zero or more parent ids. Root items have parent_ids = '{}'.
• paths text[] — full dot-joined paths, one per ancestor lineage. Trigger-maintained from parent_ids + slug. Lookup via '<path>' = ANY(paths).
• Slug convention: lowercase, vowel-elided where natural (prjx, mai, mbrn), kebab-allowed for multi-word leaves (spring-clean).
• Aliases: aliases text[] keeps old slugs searchable after rename.
• tags text[] — free-vocabulary cross-cutting labels (work, dev, home, tech, …). GIN-indexed. No fixed vocabulary.
• management text[] — how the project is run: self, mai, external. An item can carry multiple modes. Empty array means "no specific management mode declared".

2.3 Lifecycle (thin)

active → done → archived

That's it. Free-text in content_md covers the nuance ("waiting on Brian," "paused until June"). No rich state machine; m flagged richer schemes as rot-prone.

2.4 Relationships

• Tree-as-DAG (parent/child within projax): items.parent_ids uuid[]. Root items have parent_ids = '{}'. Any item may name multiple parents — the same row then appears under each branch with paths inherited from each lineage.
• External refs (projax.item_links): each row links an item_id to a typed external resource — caldav-todo, gitea-issue, github-repo, mai-task, mai-project, mbrian-node, url, etc. Used both for aggregating tasks and for soft cross-references.

3. Schema (Postgres, msupabase, schema projax)

create schema if not exists projax;

create table projax.items (
  id            uuid primary key default gen_random_uuid(),
  kind          text[] not null default '{}',          -- ['area'] or ['project'] (multi-tag allowed for future)
  title         text not null,
  slug          text not null,                          -- local segment, no dots
  path          text not null,                          -- computed, e.g. 'home.spring-clean'
  parent_id     uuid references projax.items(id) on delete restrict,
  content_md    text default '',
  aliases       text[] not null default '{}',
  metadata      jsonb not null default '{}'::jsonb,
  status        text not null default 'active',         -- active | done | archived
  pinned        boolean not null default false,
  archived      boolean not null default false,
  start_time    timestamptz,
  end_time      timestamptz,
  parent_ids    uuid[] not null default '{}',
  paths         text[] not null default '{}',
  tags          text[] not null default '{}',
  management    text[] not null default '{}',
  created_at    timestamptz not null default now(),
  updated_at    timestamptz not null default now(),
  deleted_at    timestamptz
);

create index items_paths_idx       on projax.items using gin (paths);
create index items_parent_ids_idx  on projax.items using gin (parent_ids);
create index items_kind_idx        on projax.items using gin (kind);
create index items_tags_idx        on projax.items using gin (tags);
create index items_management_idx  on projax.items using gin (management);
create unique index items_root_slug_uniq
  on projax.items (slug) where cardinality(parent_ids) = 0;

create table projax.item_links (
  id            uuid primary key default gen_random_uuid(),
  item_id       uuid not null references projax.items(id) on delete cascade,
  ref_type      text not null,                          -- 'caldav-todo' | 'gitea-issue' | 'github-repo' | 'mai-task' | 'mai-project' | 'mbrian-node' | 'url' | ...
  ref_id        text not null,                          -- opaque external identifier
  rel           text not null default 'contains',       -- 'contains' | 'related' | 'blocked-by' | 'derived-from'
  note          text,
  metadata      jsonb not null default '{}'::jsonb,
  created_at    timestamptz not null default now(),
  unique (item_id, ref_type, ref_id, rel)
);

create index item_links_item_idx on projax.item_links (item_id);
create index item_links_ref_idx on projax.item_links (ref_type, ref_id);

3.1 Path triggers (multi-parent)

paths is a text[] maintained by compute_item_paths(parent_ids, slug, self_id):

• For root items (parent_ids = '{}'), paths = [slug].
• Otherwise, look up every parent's paths, append .<slug> to each, dedupe and sort. The recursion is implicit — parents' paths are kept up to date by the same trigger, so children just consume the precomputed prefixes.
• Cycle detection: the function rejects when self_id appears anywhere in the recursive ancestor closure (WITH RECURSIVE closure ...). Plus a defensive direct-self-parent check.

Two BEFORE triggers and two AFTER triggers cooperate:

• items_before_write (BEFORE INSERT/UPDATE) — cycle guard + new.paths := compute_item_paths(...).
• items_check_slug_collision (BEFORE INSERT/UPDATE) — for each parent in new.parent_ids, refuse if another row already uses new.slug under that parent.
• items_after_reparent (AFTER UPDATE of slug/parent_ids) — DFS over descendants via refresh_item_paths_recursive, parent-first ordering. A session GUC projax.refreshing_paths short-circuits the inner UPDATEs so the cascade fires exactly once.
• items_after_delete (AFTER DELETE) — scrubs the deleted id from every other row's parent_ids array (we have no FK integrity on array elements; this is the manual cascade).

3.2 The items_unified view

After Phase 1.5 mai.projects is a derived projection (see §3.4), so the view collapses to a thin projection over projax.items:

create view projax.items_unified as
select
  i.id, i.kind, i.title, i.slug, i.paths, i.parent_ids, i.content_md,
  i.aliases, i.metadata, i.status, i.pinned, i.archived,
  i.start_time, i.end_time,
  'projax'::text as source,
  (select l.ref_id from projax.item_links l
   where l.item_id = i.id and l.ref_type = 'mai-project' limit 1) as source_ref_id,
  i.tags, i.management, i.created_at, i.updated_at
from projax.items i
where i.deleted_at is null;

source is always 'projax' (kept for forward compat); source_ref_id surfaces the mai-project pointer when one exists so the UI can show "mai id: foo".

Soft-delete tightening (migration 0013, Phase 3d). Every item_links row is implicitly tied to its parent item's life: on soft-delete (projax.items.deleted_at flips NULL → not-null) a BEFORE-UPDATE trigger cascades a DELETE FROM projax.item_links WHERE item_id = NEW.id in the same statement. The migration also one-shot-cleans the ~12 orphan mai-project rows that predate this trigger. Result: count(item_links WHERE ref_type=X) and count(items_unified WHERE source_ref_id IS NOT NULL) stay in lock-step — TestItemsUnifiedSurfacesMaiPointer regression-guards this.

3.3 Classification overlay

Items can land at root in two ways:

• The backfill in migration 0007 heuristic-assigned every existing mai.projects row to one of the seven seeded areas (dev, sports, work, home, health, finances, social). None ended up at root in this pass.
• The reverse sync trigger (§3.4) drops every NEW mai.projects row at root with management = ['mai'], leaving m to classify it via /admin/classify.

/admin/classify surfaces items where cardinality(parent_ids) = 0 AND 'mai' = ANY(management). The inline form posts to /i/{path}/reparent to move the item under a chosen parent without touching its other fields.

3.4 mai.projects bidirectional sync (Phase 1.5)

mai.workers, mai.tasks, mai.sessions, mai.messages, mai.metrics and mai.pwa_head_pins hold FKs into mai.projects(id), so the table cannot be replaced by a view. Instead it becomes a derived projection kept in sync by triggers:

• Forward (projax.sync_to_mai, AFTER INSERT/UPDATE/DELETE on projax.items) — when an item has 'mai' = ANY(management), upsert/update/delete the matching mai.projects row. Slug stays the join key (mai.projects.id = projax.items.slug at creation), but FK targets cannot be renamed, so projax slug and mai id may drift after a rename; the cross-system pointer in item_links(ref_type='mai-project') remains stable.
• Reverse (projax.sync_from_mai, AFTER INSERT/UPDATE/DELETE on mai.projects, SECURITY DEFINER so mai role writes can fan out into projax.items which projax_admin owns) — mirror the change into a projax.items row, dropping new rows at root with management = ['mai'] so /admin/classify can pick them up.
• Cycle prevention — both functions short-circuit when pg_trigger_depth() > 1 (the natural recursion case) and additionally honour a projax.in_sync session GUC as belt-and-braces.

The mai.projects → projax.items reverse trigger requires manual prereqs on msupabase:

GRANT INSERT, UPDATE, DELETE, TRIGGER ON mai.projects TO projax_admin;
DROP POLICY IF EXISTS projax_write ON mai.projects;
CREATE POLICY projax_write ON mai.projects FOR ALL TO projax_admin
  USING (true) WITH CHECK (true);

(documented in 0008's header and the README).

4. Interfaces

4.1 Phase 1 + 1.5 — Web frontend (this build)

Web frontend at https://projax.msbls.de, single binary, served by the same Go process that talks to msupabase.

Pages:

1. Tree view (/) — DAG rendering: every item appears under each of its parents. Status / management / tag chips per row. Filter bar at the top combines a debounced search input with chip rows for tags, management, status, and has-link (caldav / gitea), plus a "show archived" toggle. Filters compose: AND across dimensions, OR within (except tags, which AND). Each chip shows the count it would yield if toggled (so work (12) means flipping that chip on lands you at 12 matching items). Status defaults to active only; archived rows hide until either the archived status chip is selected AND the show-archived toggle is on. The URL is the source of truth — every filter is in the query string (?q=…&tag=…&mgmt=…&status=…&has=…&show-archived=1), so any view is bookmarkable. HTMX swaps the tree-section in place on every chip click and on keyup of the search input (200ms debounce); hx-push-url keeps the browser URL in sync. ×N badge on multi-parent items shows how many paths they live at.
2. Item detail (/i/{path}) — {path} matches any entry in paths; both work.paliad and dev.paliad resolve to the same row. The page shows the primary path plus an "Also at: …" breadcrumb for the others. Edit form supports title, slug, multi-select parents, status, tags, management, pinned/archived, content. Save POSTs to /i/{path}.
3. New item (/new?parent={path}) — same form shape; the parent query pre-selects one parent option, m can pick more.
4. Classify (/admin/classify) — surfaces items at root with 'mai' = ANY(management). Inline HTMX form sets the first parent. POSTs to /i/{path}/reparent. Phase 3o consolidation: /admin/classify, /admin/caldav, /admin/bulk now live under a single /admin index page (one card per tool with quick stats — orphan count, calendar count, item count). The header nav exposes one admin link rather than three separate ones. A system panel below the cards surfaces version, last applied migration, MCP status, and a parallel-probed health view (DAV / Gitea / Supabase) cached for 30 s.
5. Bulk edit (/admin/bulk, Phase 3d) — desktop-only multi-row editor. Top: a filter form that reuses the same query params as the tree page (q, tag, mgmt, status, has, show-archived) so URLs translate 1:1 between tree and bulk views. Below: a flat checkbox list of every matching row (slug, primary path, tags, mgmt, status). An action bar at the top supports four operations: add tag, remove tag, set management (mai/self/external/clear), set status (active/done/archived). One POST to /admin/bulk/apply runs every change inside a single transaction (rollback-on-error). Inline per-row chip edits use POST /admin/bulk/chip for one-off add/remove without ticking a checkbox; only the affected cell re-renders.
6. Auth — projax's own /login (mBrian pattern). Same Supabase backend, per-host cookies (no Domain attribute).

4.2 Tags + management

• Tags (projax.items.tags text[], GIN-indexed) — free vocabulary, no fixed list. Cross-cutting labels for "work-y dev things" (['work', 'dev']), "health priorities" (['health']), etc. Filter chips at / reveal which tag-flavoured slices exist.
• Management (projax.items.management text[], GIN-indexed) — declarative mode flags:
  • mai — bidirectional sync with mai.projects. Adding/removing mai toggles the mai.projects mirror on/off (with FK safety: removal fails if workers/tasks still reference the project).
  • self — m runs this manually; otto does not orchestrate.
  • external — owned by a third party; projax mirrors metadata only.

Mai.projects backfilled rows arrive with management = ['mai']. m can layer self on top without dropping mai sync.

Area-tag backfill (migration 0012, Phase 3d). Backfilled mai-managed items landed with tags = '{}', so the tree-page tag filter chips had no signal to filter on. Migration 0012 one-shot-populates tags with the slug of each area an item lives under (so an item under work.flexsiebels picks up tag=work; a multi-parent item under work.paliad AND dev.paliad picks up ['dev', 'work']). The migration only touches rows where tags = '{}'; once m has edited an item's tags it is left alone. Going-forward bulk recovery uses /admin/bulk instead of repeating the migration.

4.2 Phase 2 — task aggregation

• CalDAV ingest — read-only mirror of m's CalDAV todo lists into item_links with ref_type=caldav-todo. Per-area mapping (e.g. home aggregates from CalDAV list "Home"). Background sync, no writeback initially.
• Gitea ingest — read-only mirror of issues on linked repos. mai.projects.repo field is a hint; per-item override possible.

4.3 Phase 3 — visualization & integrations

• Excalidraw view — visual roadmap, dependencies, area-overview boards. Generated from items_unified.
• MCP — mcp__projax__* so otto and other workers can read/write projax. Pattern follows mcp__mai__.
• Otto-PWA integration — read-mostly surface for m's day-to-day. Defer until projax has lived long enough to know what otto actually needs.

5. Tech stack

• Backend: Go single binary. pgx for Postgres. HTMX-driven HTML rendered server-side (Go html/template). No frontend build step. Static assets bundled with embed. Matches m's dotfile-stated preferences.
• Database: msupabase, schema projax (new). View projax.items_unified reads across projax.* + mai.projects. RLS off for v1 (single-user).
• Hosting: Dokploy on mlake, domain projax.msbls.de. Tailscale-only network (no public exposure).
• Repo: m/projax (already exists). Branch strategy per project CLAUDE.md (main + short-lived feat/fix branches, no dev branch initially).

Alternative considered: SvelteKit + Bun (matches flexsiebels). Rejected for v1 — CRUD admin scale doesn't justify the build chain.

6. Migration plan

Three phases, smallest viable each:

1a — Schema + seed: create projax.items, projax.item_links, path trigger. Seed the seven day-one areas (dev, sports, home, work, health, finances, social) as kind=['area'], parent_id=null.

1b — Adapter view: deploy items_unified. All 28 mai.projects rows now visible in the tree as top-level orphans.

1c — Classification UI: the /admin/classify page so m can drag mai.projects rows under areas. Drag = create a projax-native item with kind=['project'] + parent_id set + item_links row pointing at the mai.projects row. mai.projects untouched; the projax row owns area assignment + projax metadata.

After 1c, m can use the system. Test rows in mai.projects either stay as orphans (ignored) or get a source-filter to hide them.

7. Out of scope

• Multi-user (single-tenant, m only)
• Mobile-first responsive (desktop browser is enough)
• Public exposure (Tailscale only)
• Generic SaaS instincts (admin panels, billing, audit logs)
• CLI surface (m has explicitly opted out)
• Bidirectional Gitea sync in v1 (read-only mirror first; CalDAV is full read/write as of phase 2.b)
• Real-time collaboration features

5. CalDAV integration (Phase 2, v1: full read/write)

m's CalDAV server lives at dav.msbls.de/dav/calendars/m/ (SabreDAV, Basic auth via DAV_USER/DAV_PASSWORD). projax v1 wires the slice m exercises day-to-day:

• Link model: a projax.item_links row with ref_type='caldav-list', ref_id=<absolute calendar URL>, metadata={display_name, calendar_color, linked_at, …}. Same item_links row pattern as mai-project / gitea-repo. An item can be linked to multiple calendars; a calendar can be linked to multiple items (rare in practice).
• Discovery (GET /admin/caldav): the binary PROPFINDs Depth: 1 against the base URL, filters out non-calendar collections (inbox/outbox), and pairs each discovered calendar with the projax item whose lowercased title or slug matches the calendar's display name. m confirms or overrides each suggestion.
• Linking (POST /admin/caldav/link / /admin/caldav/unlink): single-row CRUD on item_links. No background sync.
• Task aggregation (item detail page): for each linked calendar, the binary REPORTs calendar-query for VTODOs and renders open + recent-completed tasks. Each row carries its server ETag and raw ICS so the writeback affordances below can do optimistic-concurrency PUTs. Errors per-calendar are logged and skipped — one bad list does not blank the section.
• Create-on-demand list (POST /i/{path}/caldav/create): MKCALENDAR at <base>/<item.slug>/ with display name <item.title>. If the URL is already in use (SabreDAV returns 405), the binary links to the existing calendar instead.
• Writeback affordances on the detail page (phase 2.b): each VTODO row exposes complete (checkbox → STATUS:COMPLETED + COMPLETED:<UTC>), reopen (STATUS:NEEDS-ACTION, COMPLETED cleared), inline edit of SUMMARY + DUE, and hard-delete via × with an hx-confirm dialog. An "Add task" form at the top of each linked calendar POSTs a fresh VTODO (UID is a server-generated RFC 4122 v4). All five actions are HTMX-driven (hx-post + hx-target="#tasks-section" + hx-swap="outerHTML"): the handler re-renders the tasks fragment so the swap reflects the post-write server state.
• Optimistic concurrency: every edit/complete/reopen/delete request carries an If-Match: <ETag> header. The handler first re-ListTodos'es the calendar (small calendars → cheap; ETags from the page render may have drifted) and uses the live ETag, so ordinary use never trips 412. When the server still returns 412 — e.g. another client edited between refetch and PUT — the section re-renders with a banner: "Task changed elsewhere since this page was loaded — refresh and retry." The cached ETag table envisioned in Phase 2.c remains parked until live REPORT-querying gets slow.
• ICS round-trip: writes that modify an existing task call ApplyVTodoEdit against the server's raw ICS so unknown properties (DESCRIPTION, CATEGORIES, X-extensions, …) survive the round-trip. Only the keys projax knows about (SUMMARY, STATUS, COMPLETED, DUE, PRIORITY, LAST-MODIFIED, DTSTAMP) get rewritten. New tasks go through BuildVTodoICS which emits a minimal but valid VCALENDAR wrapper with RFC 5545 folding at 75 octets and CRLF terminators.
• Multi-parent items keep ONE list per item — the URL is derived from the slug, not the path. paliad gets /dav/calendars/m/paliad/ whether it lives at work.paliad, dev.paliad, or both.
• Authorisation: writeback handlers reject calendar URLs not currently linked to the item, so a crafted form can't route writes to arbitrary collections.
• VEVENT reading (Phase 3l) — read-only event listing parallel to VTODO support, closing the mgmt-parity gap before teardown. caldav.ListEvents(calendarURL, ListEventsOpts{TimeMin, TimeMax}) issues a REPORT calendar-query with a server-side <c:time-range> filter and parses VEVENT blocks into an Event{UID, Summary, Start, End, AllDay, Location, Description, Recurring, URL} struct. DATE-only DTSTART values are detected at the raw-line level (the param strip in splitLine would otherwise lose VALUE=DATE); hasDateOnlyParam flips AllDay=true. RRULE-bearing events surface with Recurring=true and only the literal DTSTART instance — projax does NOT expand RRULE at v1; m clicks through to his calendar app for the recurring picture.
• Out of scope (still parked): RRULE expansion, VEVENT writeback (create/edit/delete events from projax — calendar app handles), iCal export of projax-managed events, recurring VTODOs, background sync, multi-calendar drag-and-drop. Phase 2.c may add a TTL'd cached_tasks table if live REPORT-querying gets slow at m's scale.

Env contract: DAV_URL (default https://dav.msbls.de/dav/calendars/m/), DAV_USER, DAV_PASSWORD. All three live in Dokploy secrets; missing → /admin/caldav renders a "not configured" notice and the detail page hides the Tasks section.

6. Gitea integration (Phase 2.d read; 3h writeback)

m's Gitea instance lives at mgit.msbls.de (token auth, automation account mAi). Phase 2.d landed read-only; Phase 3h extended it to read + write for the four most common operations:

• Link model: a projax.item_links row with ref_type='gitea-repo', ref_id='<owner>/<repo>' (e.g. m/projax, mAi/paliad, HL/mWorkRepo). The Phase 1.5 backfill already populated this row for every mai.projects with a repo field. An item can carry multiple gitea-repo links — projax sums them on the detail page.
• Issues section (item detail page, rendered when at least one gitea-repo link exists): per-repo block with open issues (#N · title · labels · milestone · assignees · updated <rel>), a ↗ Gitea repo link in the header, and a disclosure for the last-30-days closed issues (up to 20). Title and number link out to htmlURL on Gitea (target="_blank"). Failed fetches (404, network) surface as a per-repo banner so one missing repo doesn't blank the section.
• Listing: GET /api/v1/repos/{owner}/{repo}/issues?state=open&type=issues&limit=50 for the open list; same shape with state=closed&since=<-30d>&limit=20 for the recent-closed disclosure. type=issues filters PRs out server-side on Gitea ≥1.20; the client also drops any pull_request != null rawIssue as belt-and-braces.
• Caching: per-process, in-memory TTL cache (~3 min) keyed by owner/repo|state so rendering the same detail page back-to-back does not hammer Gitea. No DB cache table at v1; a projax.cached_issues would land in 2.f if perf bites.
• Auth: Authorization: token <GITEA_TOKEN>. The token is the mAi automation account (GITEA_TOKEN_AI in .env.age) — keeps projax's reads attributed to mAi for audit purposes, same as how every other automated worker talks to Gitea. Missing token + non-empty URL → fail-fast at boot.
• Writeback (Phase 3h) — four operations on the Issues section + dashboard Issues card:
  • Close an open issue (PATCH /repos/{o}/{r}/issues/{n} with {"state":"closed"}) — single click, no confirm modal (cheap to reopen).
  • Reopen a closed issue (same endpoint with {"state":"open"}).
  • Comment on an issue (POST /repos/{o}/{r}/issues/{n}/comments with {"body":...}).
  • Create a new issue under a linked repo (POST /repos/{o}/{r}/issues with {"title":..., "body":...}).
  • Authorisation: writeback handlers reject any repo form value that isn't linked to the item via a gitea-repo item_link. Prevents form-crafted writes against arbitrary repos.
  • Token permission: the mAi token (GITEA_TOKEN_AI) needs write scope on m's repos. A 401/403 surfaces as gitea.ErrForbidden and renders an inline "Gitea token lacks write access" banner so the page never breaks.
  • Cache busting: every successful writeback invalidates both the Gitea per-repo cache entries ({repo}|open + {repo}|closed-recent) and the dashboard 60s TTL (all keys) so the next render reflects the upstream change.
  • Parked further: PR creation, label edit (folded in only if cheap), issue title/body edit, comment edit/delete, webhook live updates, cross-repo bulk ops, issue templates.

Env contract: GITEA_URL (e.g. https://mgit.msbls.de, no /api/v1 suffix), GITEA_TOKEN. Both live in Dokploy secrets; GITEA_URL unset → integration off cleanly (Issues section just doesn't render). GITEA_URL set but GITEA_TOKEN missing → refuse to start.

7. MCP surface (Phase 3a)

projax exposes its data + writes through an MCP server mounted on the same binary at /mcp/rpc. Mirrors the conventions of mcp__mai__* and mcp__mai-memory__* — one tool per coherent operation, snake_case names, structured JSON results carried inside the standard MCP content[].text envelope.

Tools

name	summary	key inputs
list_items	List items with filters	parent_path, tags[], management[], kind[], status, q, has_repo, has_caldav, limit
get_item	Fetch one item by id or path	id xor path, include_links (default true)
create_item	Create a new item	slug, title, parent_paths[], kind[], tags[], management[], content_md, status, metadata
update_item	Partial update of an existing item	id xor path, any subset of editable fields
delete_item	Soft-delete; refuses on live descendants unless cascade=true	id xor path, cascade
list_links	List item_links attached to an item	id xor path, optional ref_type
add_link	Add an external item_link	ref_type, ref_id, rel, note, metadata
remove_link	Delete an item_link by id	link_id
search	Ranked substring search across title/slug/aliases/content_md	query, limit
tree	Nested tree (multi-parent items appear under each branch)	root_path, depth

Output shape

All tools return a JSON object inside a single MCP text-content block. list_items, list_links, search, tree return {count|roots, items|links|tree}. get_item and write tools return a single itemView / linkView with snake_case fields matching projax.items_unified's columns.

Multi-parent semantics

• list_items with parent_path='work' matches any item whose paths[] contains a path equal to work or beginning with work. — multi-parent items surface from any ancestor.
• get_item resolves either by uuid or by any path the row publishes; dev.paliad and work.paliad return the same row.
• create_item accepts parent_paths as a string array: [] for a root, ['work'] for single-parent, ['work', 'dev'] for multi.
• update_item with a non-nil parent_paths replaces the full parent list; pass the current list plus the new one to add a parent.
• tree honours multi-parent — the same uuid appears under each branch with its inherited path as the node's path field.

Transport + auth

• HTTP+JSON-RPC 2.0 over POST /mcp/rpc (no SSE needed at v1 — every tool returns synchronously).
• Bearer auth via Authorization: Bearer <PROJAX_MCP_TOKEN>. /mcp/* paths are exempt from the cookie auth middleware so API callers don't need a Supabase session.
• A GET on /mcp/rpc returns a small descriptor {server, version, protocolVersion, tools[], authRequired} for ops smoke-testing.

Bridge for stdio MCP clients

~/.claude/mcp/projax.sh is a tiny bash bridge: reads NDJSON JSON-RPC frames from stdin, POSTs each to ${PROJAX_MCP_URL}/rpc with the Bearer header, writes the response back to stdout. The repo-root .mcp.json exposes both wirings:

• An http server entry for clients that speak HTTP+MCP natively.
• A command server entry (referenced separately under ~/.claude/mcp/projax.sh) for stdio-only clients.

Neither encodes a token; both interpolate ${PROJAX_MCP_TOKEN} at session start.

Env contract

• PROJAX_MCP_TOKEN — 32-char Bearer secret. Unset → /mcp/* returns 404 (off cleanly, the web UI keeps working). Set → routes mount, every request requires the matching Bearer.

Out of scope (parked):

• Server-pushed notifications / SSE — phase 3b.
• Bulk import/export tools — phase 3b.
• Otto-PWA integration that consumes this surface — separate worker.

Documents / dated artifacts (Phase 3c)

The PER standard (docs/standards/per.md) needs a (item, event_date) pair as its backing store. Phase 3c lands it.

• Schema: migration 0011_item_links_event_date.sql adds projax.item_links.event_date date (nullable) and a partial index. Day granularity per the PER spec; time-of-day is intentionally out of scope.

• Ref-type convention: existing types (caldav-list, gitea-repo, gitea-issue, mai-project, …) keep their meaning. Phase 3c adds three convention names for dated artifacts:

  • document — generic external pointer (URL, local file path, Drive link, …)
  • note — short text snippet; the body lives in note or metadata.body
  • url — bookmarked link (rendered as a clickable anchor)

  The schema doesn't enforce these — the column is text — but the UI uses them to render differently.

• Detail page → Documents section (renders unconditionally on every /i/{path} page; empty-state copy when no dated links exist):

  • Lists every item_link with event_date IS NOT NULL for the item, ordered event_date DESC, created_at ASC.
  • Each row shows the computed PER (<primary-path>.<YYMMDD>[.<collision-tag>]), a ref-type badge, the ref_id (clickable for url), the optional note, and a small × to remove.
  • Add form (top of section): ref_type | event_date | ref_id | note. POSTs to /i/{path}/links/add → HTMX swap.
  • Collision tags (.a, .b, …) are computed at render time only, never stored. The first link on a date is bare; the second gets .a, the third .b. Order is by created_at within the same date.

• URL resolution for PER-cited paths: handleDetail first tries the literal path; if it 404s and the trailing segment looks like YYMMDD, it retries with the date stripped and surfaces the parsed date as a render hint so the Documents section can scroll to / highlight the matching row. Invalid dates (Feb 30, 99/99/99) are not stripped — they hit the original 404 path.

• MCP: add_link accepts an optional event_date: "YYYY-MM-DD". Existing callers without it keep working. linkView.event_date surfaces the stored value on the response side. The conflict policy on duplicate (item_id, ref_type, ref_id, rel) is COALESCE(new, old) for note/event_date so partial updates don't clobber an earlier date by accident.

• Anti-forgery on remove: the /links/remove handler verifies the link's item_id matches the URL's item before deleting — a crafted form can't snipe a link that belongs to a different item.

Out of scope (parked):

• Recurring dated artifacts (RRULE-style). Flatten for now.
• Cross-PER linking syntax / forward-jump anchors. Phase 3d+ if m needs it.

Out of scope (permanent — decided 2026-05-17):

• File uploads / in-projax file storage. projax item_links are references, not files. The PER ({path}.{YYMMDD}) names where a document lives elsewhere — mFin/, the filesystem, a URL — and the source-of-truth stays there. Do not propose adding multipart uploads, a documents bucket, or an attachments table; m killed that on 2026-05-17. The "documents" surface is intentionally a list of (ref_type, ref_id, event_date, note) rows and nothing more.

8. Open questions (post-PRD)

• Path-trigger correctness under cycle attempts: enforce acyclicity via check in trigger.
• mai.projects test row hiding: drop them from the view via name pattern, or surface them with a "test" tag?
• Classification promotion semantics: when a mai.projects row is promoted, does the projax item replace it in the unified view, or do both still appear? Default: projax wins, view filters out adapted mai rows.
• Auth: re-use flexsiebels Supabase auth, or simpler shared-secret cookie? msupabase auth is heavier than v1 needs.
• mBrian topic-hub linkage: do we auto-suggest mbrian topic links when an item is created with a matching slug? Defer to phase 3.

Dashboard / daily-driver view (Phase 3e)

A single landing surface at /dashboard that aggregates open work and recent activity across every linked project, so projax can be opened first thing in the morning instead of clicking through each project's detail page.

Sections (each a card, count in header):

1. Open tasks — every open VTODO (Status != COMPLETED/CANCELLED) from every caldav-list item_link, fanned out via a 4-worker pool to avoid DAV-server hammering. Bucketed by due date: Overdue (red), Today, Tomorrow, This week (≤7d), No due. Sort: overdue first, then due asc with no-due last; ties by priority desc, summary asc. Capped at 30 rows; total + per-bucket counts surface in the section header. Each row has a ✓ button that POSTs /dashboard/task/done with calendar_url + uid, flips the VTODO to COMPLETED via the existing PUT path, busts the dashboard cache, and re-renders the full section (so the row vanishes and counts decrement).
2. Open issues — every open Gitea issue from every gitea-repo item_link, sorted updated_at desc. Read-only (Gitea writeback parked). Reuses the existing GiteaDeps.Cache (3-min TTL) so repeated dashboard loads share Gitea hits with the detail page.
3. Recent documents — every dated item_link (event_date IS NOT NULL) with event_date >= now - 30d, joined to its parent item. Sorted newest-first. Each row renders the canonical PER ({primary_path}.{YYMMDD}), ref_type badge, note, ref_id link, and project path. Capped at 30.

Filters: small chip row at the top reuses tree_filter.go URL params (tag, mgmt, has) so /dashboard?tag=work scopes all three cards to work-tagged items. The same filter has another use as the cache key — /dashboard and /dashboard?tag=work are independent cache entries.

TTL cache: 60s in-memory map keyed by the encoded TreeFilter. The cache is single-replica only (no shared state needed at single-user scale). The ✓-mark-done handler explicitly invalidates the cache so the row disappears immediately on the next render.

Out of scope for 3e: real-time updates, full per-section pagination, dashboard-as-root-landing. Tree at / stays the default surface; nav bar adds a "dashboard" link so m chooses when to switch.

Phase 3g additions:

4. Stale projects — items with 'mai' = ANY(management) AND every linked Gitea repo's updated_at older than 60d AND zero open VTODOs across linked CalDAV lists AND zero open Gitea issues. Sorted longest-stale first, capped at 20. Each row shows the project path, the quiet repo, and "last active Nd ago" with the absolute date on hover. "Consider archiving?" framing only — no auto-action.
   • Uses the same 4-worker pool as the issues card. Per-item task/issue counts are reused from the already-aggregated Tasks/Issues cards (no second DAV/Gitea pass).
   • Items with NO linked repo are skipped — without a signal there is no way to call them stale.
   • When an item has multiple linked repos, ALL must be older than the cutoff (so an item with one quiet repo and one busy repo is NOT stale).
5. Last-refresh indicator — small "updated Nm ago · cached" / "updated Nm ago · fresh" line at the top of the dashboard chrome, derived from the cached payload's BuiltAt timestamp.
6. Force-refresh button — ↻ refresh link that adds ?refresh=1 to the current URL. The handler invalidates the matching cache key and re-runs the full aggregation. HTMX swaps the section in-place.
7. Empty-card collapse — when no filter is active AND a card has zero rows, render a one-line No open tasks. / No open issues. / No recent documents. note instead of the full empty-state block. With a filter active the card chrome stays so m can distinguish "filter hid the data" from "no data".

Phase 3l addition — Events card (closes the mgmt-parity gap):

8. Events — every VEVENT in the next 7 days across every caldav-list item_link, fanned out via the same 4-worker pool. Time-range filter is server-side (RFC 4791 <c:time-range>), so the DAV server returns only what the window contains. Grouped by day with German "Today" / "Tomorrow" / weekday labels lifted from the mgmt cockpit's wording. Sort within day: start asc, summary asc as tiebreaker. Cap 50. Each row: start time (or "ganztägig" for all-day DATE events), project path link, summary, location, and a ↻ badge when the source VEVENT has an RRULE (the dashboard never expands recurrences — only the literal DTSTART instance). Empty-collapse: with no filter and zero events, the card renders "No upcoming events." inline.

Graph view (Phase 3f)

A read-only top-down DAG render of every projax item at /graph, server-rendered inline SVG — no client-side layout library, no Excalidraw file. Trade-offs: m gets a single page that prints, downloads, and reflows in a regular browser; no drag-to-rearrange (read-only is enough for the daily glance).

Layout (in internal/graph):

• LayerByLongestPath(nodes) → each node's layer is max(layer(parent)) + 1, so a multi-parent item like paliad (under both work and dev) sits below whichever lineage is longer. Roots are layer 0. Depth-capped at 64 to bail loudly on cycles (the schema trigger already forbids cycles on write).
• OrderInLayer(layers) — alphabetical by slug inside each layer for deterministic rendering. No barycenter / crossing-minimisation pass — at m's scale (≤ a few hundred items) the readability cost is negligible.
• Compute(nodes, opts) returns positions + edges + canvas size. Pure-Go, no external deps. Unit-tested with multi-parent, longest-path-wins, sort, and cycle-guard fixtures.

Node styling:

• 130×44 px box per item.
• Border colour = management mode: mai blue, self green, external orange, mixed dashed purple, unmanaged grey.
• Box opacity = status: active 1.0, done 0.6, archived 0.3.
• Slug as the main label; first three tags rendered as small pills along the bottom (+N overflow); ×N badge top-right for multi-parent items.
• <title> element gives a hover tooltip with title + status + management.
• Each node wrapped in an <a href="/i/{path}"> so a click navigates to the detail page.

Filter chips: same tree_filter.go URL params (q, tag, mgmt, status, has). Default behaviour is to dim non-matching nodes (opacity 0.15) so the structural relationships stay visible. ?isolate=1 switches to hide-non-matching mode and drops every edge whose endpoint is hidden.

Print + download: SVG is inline so the browser's "Print" produces a real vector page. ?download=svg serves the raw SVG with Content-Disposition: attachment; filename="projax-graph.svg" — useful for stashing a snapshot in slides or in mBrian.

Out of scope for 3f: editable layout (drag-to-rearrange), Excalidraw file export, auto-refresh on item changes.

Mobile responsiveness (Phase 3i)

Pure CSS + minimal template tweaks make every projax page legible and tappable on m's phone (via Tailscale). The original "Otto-PWA covers mobile" plan is dropped — projax's own pages need to render on phone even if Otto-PWA later embeds or links to them.

Breakpoints (CSS media queries on web/static/style.css):

• ≤ 768px (tablet): chip strips become horizontal-scrollable, tables (/admin/bulk, /admin/classify) flip to card lists, dashboard cards widen, edit forms drop to single column. Touch targets bump to ≥ 44px on buttons.
• ≤ 480px (phone): base font nudges to 15px so default body text is legible without pinch-zoom. Header nav wraps. The bulk-table primary-path column hides on phone (slug + tags + actions are enough).
• ≥ 1280px (wide laptop): main column widens to 1200px and the dashboard grid splits to 2 columns with the stale card spanning both.

Layout principles:

• Viewport meta on every page (<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">); enforced by TestLayoutHasViewportMeta.
• Touch targets ≥ 44px on phone for buttons + chip toggles. Chip strips use flex-wrap: nowrap + overflow-x: auto so the row scrolls instead of wrapping into a tall block.
• Tables → cards: display: block on tbody/tr/td with td::before { content: attr(data-label); } — when m wants per-column labels visible on mobile, add data-label="…" to the <td>.
• Forms: native <input type=date> etc. so iOS pickers fire (already in place).

SVG /graph special case:

• Wrapped in .graph-canvas { max-width: 100vw; max-height: 75vh; overflow: auto; } so the inline SVG scrolls + pinch-zooms inside its container instead of overflowing the page.
• "Fit to screen" toggle (.graph-canvas.fit .graph-svg { width: 100%; }) flips between natural-size and viewport-sized renders. Native pinch-zoom remains available via the viewport meta.

Out of scope:

• Push notifications (Otto-PWA's domain).
• Dark mode toggle.
• Right-to-left layout.

PWA install (Phase 3j)

projax is now installable as a real PWA — iOS Safari "Add to Home Screen" produces a standalone-launching icon and Android Chrome offers the same install flow. Scope is "install affordance," NOT full offline mode.

Manifest (/static/manifest.webmanifest, served with application/manifest+json via mime.AddExtensionType in web.init):

• name / short_name: "projax"
• start_url: /dashboard (the daily-driver surface m wants on tap)
• scope: /
• display: standalone
• theme_color / background_color: #1a1a1a (matches login-page palette)
• icons: 192×192, 512×512, and a 512×512 maskable variant with ~12% safe-zone padding

Icons (/static/icon-{192,512,maskable}.png): stdlib-only generation via cmd/icongen — go run ./cmd/icongen rewrites them from the source design. Stylised "p" monogram on a dark ground with an accent stripe. Re-run when the brand or palette changes; the PNGs are checked in.

Service worker (/static/sw.js):

• On install: pre-cache /static/style.css + manifest + icons.
• On activate: prune stale caches from earlier CACHE_NAME versions.
• On fetch (GET only): network-first with cache fallback on failure. Successful GETs are stashed for the next offline render.
• Explicitly skipped: any non-GET request, anything under /mcp/.

This is deliberately the smallest correct service worker. Mutations (CalDAV/Gitea writeback, MCP) require the network; m airplane-modes → he sees the last cached read view but can't change anything until reconnected.

Layout meta: theme-color, apple-mobile-web-app-capable=yes (iOS treats as standalone), apple-mobile-web-app-status-bar-style=black-translucent, apple-mobile-web-app-title=projax, plus the <link rel="manifest"> + <link rel="apple-touch-icon"> chain. Login template carries the same set so a first-time install from /login works the same as from /dashboard.

Tests: TestManifestServedWithCorrectMIME, TestServiceWorkerServed, TestIconsServed, TestLayoutHasManifestAndAppleTouchIcon.

Out of scope for 3j: push notifications, background sync, full offline write mode, splash-screen tuning.

12. Timeline view (Phase 4a)

A chronological "what's happening in my life by date" surface at /timeline, nav-linked next to /dashboard, /graph, /admin. Different shape from the dashboard (which is "right now") — the timeline is a scrollable spine that braids every dated thing in projax under its anchor date.

Sources (each row carries a (date, kind, item, label, link) tuple):

1. CalDAV VTODOs with a DUE date — open ones plus completed/cancelled in the recent past (anchor: LAST-MODIFIED for done/cancelled, otherwise DUE).
2. CalDAV VEVENTs with DTSTART in window — past 30 days and future 90 days by default. DTEND drives the duration hint ((2 days) / (1h)).
3. Dated projax.item_links (event_date IS NOT NULL) — letters, notes, documents, URLs anchored to a date. Surfaced under the canonical PER ({primary_path}.{YYMMDD}).
4. Item creation events — projax.items.created_at::date rendered as a muted "added X to projax" marker.

Items without a date never appear here — the tree/graph/dashboard cover the rest. Gitea-issue activity is explicitly out of scope for 4a (already on the dashboard).

Layout:

• Vertical spine. Each day is a <li class="spine-day"> with a header and per-day row list. Days with zero rows collapse — no header emitted.
• Default order is newest first; ?order=asc reverses both the outer day list and (implicitly) the reader's mental model. Within a day rows sort: timed events → all-day events → VTODOs → docs → creation markers, ties broken by summary / PER / slug.
• Today / Tomorrow get sticky pills next to the day header; the spine border-left highlights those days in the accent / ok colour.
• Far-future rows (Date > today+30d) get .far-future opacity 0.5 so the foreseeable future stands out from the speculative future.

Time window:

• Default: past 30 days through next 90 days.
• ?from=YYYY-MM-DD&to=YYYY-MM-DD overrides both bounds (to is inclusive in URL terms; the handler shifts to exclusive internally).
• ?before=YYYY-MM-DD advances the window into the past for "older" pagination.
• ?when=past / ?when=future clamps to the half-line containing today.

Filters:

• Reuses the tree filter strip — ?q=, ?tag=, ?mgmt=, ?has= — so the timeline can be scoped to "work things" or "anything mentioning paliad" with the same vocabulary as / and /dashboard.
• Timeline-specific narrowing: ?kind=todo,event,doc,creation (multi-select; default all four). ?when= for past/future split.

Affordances on rows (per the 4a scope-expansion message):

• VTODOs: ✓ complete, ✎ edit (summary + due), × delete — using the existing /dashboard/task/done|edit|delete handlers. The dashboard's Tasks card grew the same edit + delete on the same day.
• Dated item_links (docs): × delete via /i/{path}/links/remove. The link-remove handler now re-renders the timeline section when the swap target is #timeline-section (it still re-renders the Documents fragment when called from the detail page).
• VEVENTs: read-only at v1 (consistent with the 3l decision). Multi-day events render once on the first day with the duration hint.
• Item creation markers: read-only display only.

Cache: 90 s in-memory map keyed by (filter, from, to, order, kinds). Looser than the dashboard's 60 s because timeline is browse-y, not action-y. The cache is invalidated wholesale on VTODO writeback (/dashboard/task/*, /i/{path}/caldav/todo/*) and on dated-link add/remove — any of those could move rows on or off the spine and the cost of a re-aggregation is cheap.

Per-item exclusion (Phase 4f):

Each item carries a timeline_exclude text[] whose values name kinds to hide from the spine: 'todos', 'events', 'docs', 'creation' (empty array = default = nothing hidden). The aggregator drops the matching source for each flagged item before fanning out — no CalDAV call is made for an item whose VTODOs are excluded, no creation marker is emitted for an item whose 'creation' kind is excluded, and so on.

The detail page (/i/{path}) still surfaces everything regardless — exclusion is a render-time concern for the timeline view only, so m doesn't lose visibility into his data, he just stops seeing it braided into the chronological spine.

URL override: ?include_excluded=1 (and the MCP include_excluded: true arg) ignore the per-item arrays and surface everything — useful for "show me what I'm hiding" peek.

Bulk action: /admin/bulk offers an "Exclude todos from timeline" / "Re-include todos on timeline" pair (the most common use case — m's home shopping list). The other three kinds (events / docs / creation) are editable per-item only.

Out of scope for 4a:

• Drag-to-create-on-date (would require write paths from a non-detail page).
• iCal export of the timeline.
• Per-row inline edit of VEVENT (use the source calendar app — the 3l read-only stance still holds for v1).
• Gitea issue created/closed activity (deferred until m asks; dashboard already covers it).

13. Theming (Phase 4b)

projax ships with an explicit dark / light toggle and a 1-year cookie that remembers the choice. Default is dark — m asked for dark-by-default; the toggle exists so light mode is one click away when the ambient lighting calls for it.

Toggle approach:

• <html data-theme="dark"> (default) or <html data-theme="light">. CSS palettes live under :root, :root[data-theme="dark"] { … } and :root[data-theme="light"] { … } in web/static/style.css. Every panel colour is a var(--foo) — the only hardcoded hex values left in the codebase are inside those two :root blocks. A future palette tweak edits the variables, not 30 selectors.
• The header nav grows a small ☀ / ☾ button (sun glyph in dark mode = "switch to light", moon glyph in light mode = "switch to dark"). Inline JS in layout.tmpl flips data-theme + the apple <meta name="theme-color"> and writes the cookie via document.cookie = — no server roundtrip on toggle. The cookie is projax_theme=dark|light, Max-Age=31536000, Path=/, SameSite=Lax, NOT HttpOnly (the toggle JS reads it).
• Layout reads the cookie server-side via themeFromRequest(r) and emits data-theme + <meta name="theme-color"> at first paint — no flash-of-wrong-theme before the script runs. The render helper injects Theme + ThemeColor into every template's data map before execution, so individual handlers don't need to know about the theme.

Palette structure:

Variable	Dark	Light	Used for
--fg	#e6e6e0	#1a1a1a	primary text
--muted	#8a8880	#6a6a6a	secondary text, slugs
--bg	#0e0e0e	#fafafa	page background
--bg-alt	#1a1a1a	#f0efe8	nav bar, code blocks, tag pills
--surface	#161616	#ffffff	card backgrounds, form inputs
--surface-hover	#1f1f1f	#f7f7f7	row hover
--border	#2c2c2c	#d8d4c8	hairline borders
--accent	#6fa7e8	#2f5d9e	links, primary buttons
--accent-fg	#0a0a0a	#ffffff	text on accent backgrounds
--warn / --ok / --bad	brighter pastels	original earthy	status colours
--highlight*	warm dark	cream	PER highlight, banner warn, overdue row
--kind-*-bg / --kind-*-fg	dark muted	original pastels	timeline kind-badges
--graph-*	brighter	original	graph node strokes & legend

Theme-color meta flips with the page theme: #161616 (dark — matches --surface, the nav bar) or #f0efe8 (light — matches --bg-alt). Apple Safari uses this to tint the iOS status bar in the installed PWA.

Standalone SVG download (/graph?download=svg) bakes the LIGHT palette inline because the downloaded asset has no parent :root providing variables, and m's existing snapshots (presentations, mBrian) expect the original print-friendly look. The Standalone flag on graphPayload flips a {{if .Standalone}} block in graph_svg.tmpl to inject the inline :root declarations only on the download path.

Login page keeps its embedded dark CSS — it's the gateway and is intentionally always dark (mirrors the lockscreen feel). The theme toggle is hidden from users until they're signed in; switching the login template's palette would only matter for a never-signed-in user.

Out of scope for 4b:

• prefers-color-scheme auto-detect (could add: read it on first visit if no cookie). v1 is manual.
• Per-page theme overrides — one global theme is enough.
• CSS transitions on the swap. The flip is instant; that's intentional.

14. Timeline MCP tool (Phase 4c-B Slice 1)

The chronological view (§12) is now reachable from MCP. The PWA's Otto-projax surface (mAi#228) consumes it to render /projax/timeline on m's phone without needing a session cookie against projax.msbls.de.

Tool name: timeline. Registered in mcp/tools.go when RegisterProjaxTools receives a non-nil TimelineBuilder (the running *web.Server satisfies it via BuildTimelinePayloadFromArgs). When the third arg is nil — e.g. in package tests that don't need timeline — the tool is silently omitted; the rest of the surface stays usable.

Input schema mirrors the URL query string of the web /timeline route, lifted to a typed JSON object:

{
  "from":   "YYYY-MM-DD (optional, default now-30d)",
  "to":     "YYYY-MM-DD (optional, default now+90d)",
  "order":  "asc|desc (optional, default desc)",
  "kinds":  ["todo","event","doc","creation"],
  "tags":   ["work","dev"],
  "mgmt":   ["mai"],
  "has":    ["caldav-list"],
  "status": ["active"],
  "q":      "paliad"
}

Output shape (see mcp.timelineView in tools.go):

{
  "days": [{
    "date": "2026-05-17",
    "label": "Today",
    "sticky": "today",
    "rows": [{
      "kind": "todo|event|doc|creation",
      "item_path": "work.paliad",
      "item_title": "paliad",
      "far_future": false,
      "todo":  {"uid","calendar_url","summary","status","due","priority"},
      "event": {"uid","summary","start","start_label","end","all_day","location","recurring","duration_hint"},
      "link":  {linkView},
      "per":   "work.paliad.260517"
    }]
  }],
  "from": "2026-04-17",
  "to":   "2026-08-16",
  "to_inclusive": "2026-08-15",
  "order": "desc",
  "kinds": ["todo","event","doc","creation"],
  "total_rows": 42,
  "built_at": "2026-05-17T16:30:00Z"
}

Times stringify into either YYYY-MM-DD (date-only) or full RFC 3339 UTC (timed), matching the convention the existing list_items / get_item tools use. Polymorphic — JSON consumers can treat the timestamp strings as opaque or parse them per-locale.

Cache: the MCP path bypasses the web-side 90 s in-memory cache. Re-aggregation per RPC call is cheap (single DB pass + the same 4-worker CalDAV fan-out), and the two cache keying schemes diverge (URL filter-state vs. JSON args). Skipping the cache here keeps invalidation simple and the data fresher.

Auth: same Authorization: Bearer ${PROJAX_MCP_TOKEN} as the rest of /mcp/rpc. No CORS allowlist needed — consumers (PWA backend, future agents) call projax server-to-server.

Collapsible detail-page sections (Phase 4e)

The /i/{path} detail page wraps each major section in a native <details> element so long Issues / Documents lists don't dominate a project page. Three section keys today (tasks, issues, documents, public); <details class="proj-section" data-section data-item-id> survives HTMX swaps because the wrappers live in detail.tmpl, not inside the swap targets.

Smart defaults (server-side open attribute):

Section	Open when
Tasks	any linked calendar has at least one open VTODO
Issues	total open issues ≤ 10
Documents	dated link count ≤ 5
Public listing	always closed (toggle is rarely flipped)

Persistence: inline JS reads localStorage["projax.section." + itemID + "." + section] on boot — "open" or "closed" — and writes it back on every toggle. User choice wins over the server default. A reset section state link in the form actions wipes every projax.section.<itemID>.* key for the current item and reloads, restoring the smart-default behaviour.

What's NOT collapsible: title + status/tag/management chip line (always visible breadcrumb), the inline edit form's standard fields (title/slug/parents/content). Only the auxiliary sections collapse — m always needs to see what an item is without expanding anything.

15. Public listing (Phase 4d)

projax becomes the source of truth for which items go on m's public portfolio (flexsiebels.de today; any future renderer via MCP). Five new columns on projax.items, all default-safe — 95% of items stay private and the partial index keeps the "show me everything public" query cheap.

Schema (migration 0014):

Column	Type	Default	Meaning
public	boolean	false	The toggle
public_description	text	''	Public-facing prose (markdown); written separately from content_md so internal notes never leak
public_live_url	text	''	Production / demo URL
public_source_url	text	''	Repo URL when m wants to expose source
public_screenshots	text[]	'{}'	Ordered list of image URLs (projax stores pointers, never bytes — same PER discipline as §3c)

Partial index items_public_idx ON projax.items (public) WHERE public = true covers the public-only query. items_unified flows the columns through automatically.

MCP contract:

• update_item accepts any subset of the five new fields as a partial-update patch (nil pointers leave the existing value alone).
• list_items gains a public: boolean filter. public=true returns only public items, public=false only private, absent returns all (current behaviour).
• get_item returns all five fields automatically — itemView always includes them, even when public=false, so consumers can preview "what would publish" without a second round-trip.

UI surfaces:

• /i/{path} detail page grows a "Public listing" fieldset: toggle + description textarea + live/source URL inputs + screenshot list editor (one row per URL, add/remove buttons, server-side empty-row drop). Values persist when public is off so toggling never destroys typed-in content.
• /admin/bulk action bar gains a public-listing select with "Make public" / "Make private" — bulk apply uses a single UPDATE per action.
• /?public=1 and /?public=0 chip parameters on the tree page narrow to public/private respectively. Active() and QueryString() round-trip the state; TogglePublic() cycles nil → true → false → nil.

Intended flexsiebels consumption pattern:

flexsiebels' Go (or Deno) backend POSTs to https://projax.msbls.de/mcp/rpc with Authorization: Bearer ${PROJAX_MCP_TOKEN}, calls list_items({public: true}), renders the response server-side. The PROJAX_MCP_TOKEN is the server-to-server credential — m never sees it. No CORS work needed; calls stay server-to-server like the existing PWA bridge (mAi#228).

What does NOT happen here:

• Flexsiebels-side rendering — separate task in m/flexsiebels.de.
• Asset hosting for screenshots — projax stores URLs; m hosts images wherever already-deployed (Imgur, S3, static-asset endpoint, …).
• A publish workflow with approval stages — single boolean is enough.

17. Calendar view (Phase 5e)

Month grid at /calendar?month=YYYY-MM — the fourth dated surface, sibling to /timeline (chronological spine), /dashboard (today/week buckets), and /graph (DAG topology). Same internal/aggregate.Aggregator data pipeline as timeline; different presentation.

Sources (per cell, anchor date is local-zone midnight of the row's date):

1. CalDAV VEVENTs in the grid window ([gridStart, gridEnd)). Event start used as the anchor; the cell shows HH:MM Summary (or just Summary for all-day).
2. CalDAV VTODOs with DUE in the window. Open todos anchor on DUE; completed/cancelled todos in the last 14 days anchor on LastModified. Overdue (DUE before today, still open) renders with a warn-coloured border accent.
3. Dated projax.item_links with event_date in the window. Note text is the row summary; ref_id's last path segment is the fallback. Muted border accent.

Not surfaced: item-creation markers (too noisy for a month grid), Gitea issues (no date anchor), untimed items (calendar is fundamentally date-scoped).

Layout — web/calendar.go layoutCalendarWeeks builds the rectangular grid:

• 7 columns Mon→Sun. mondayWeekday(t) converts Go's Sunday=0 default to the German Monday=0 convention.
• Leading days from the previous month fill the first row's gap before the 1st. Trailing days from the next month pad to the last row's Sunday. Both carry IsAdjacent so CSS can grey them out.
• Each cell caps visible rows at calendarMaxRowsPerCell (3). Overflow becomes "+N more" linking to /timeline?from=YYYY-MM-DD&to=YYYY-MM-DD for a focused single-day view.
• Today's cell carries IsToday → CSS adds an accent border + "Heute" pill.
• Per-cell rows sort: timed first (by HH:MM), then by kind rank (event < todo < doc), then by summary.

Filter integration — reuses TreeFilter from web/tree_filter.go. Same query keys (q, tag, mgmt, has) plus a calendar-specific kind=event,todo,doc multi-select. The chip strip uses HTMX hx-target=#calendar-section for in-place swaps; the page chrome (month label + prev/next nav) stays outside the swap because chip filtering doesn't change month.

Cache — cache.TTLCache[*calendarPayload] keyed by (filter, month, kinds) at 60s, matching the dashboard's cadence. ?refresh=1 invalidates the entire calendar cache.

Mobile breakpoint (≤480px) — the 7-column grid is unreadable on a 360px-wide phone, so the CSS collapses to a vertical list-of-days. The LongLabel field (e.g. "Mi., 14. Mai") is hidden on desktop and revealed at the breakpoint to compensate for the absent weekday column header. Adjacent-month cells drop out entirely on mobile so the list is calendar-scoped.

German register — month and weekday labels in German throughout (Mai 2026, heute, Heute, Mi., 14. Mai). Rest of the app stays English; the calendar surface reads more naturally in German for m's usage.

• projax.items + projax.item_links migrations in db/migrations/
• Path trigger + tests
• projax.items_unified view
• Go binary: HTTP server, pgx pool, html/template + HTMX, embed static
• Pages: tree, detail, new, classify
• Auth: msupabase session cookie OR shared-secret (decide in 1a)
• Dockerfile + Dokploy config for projax.msbls.de
• Seed migration for the seven day-one areas
• README + run instructions

18. Layout: sidebar + bottom-nav (Phase 5g)

Top-nav <header> retired. Layout chrome now mirrors mBrian's surface so the two apps feel consistent on the same device.

Desktop (≥768px) — fixed-left <aside class="projax-sidebar">:

• Width via --projax-sidebar-width (default 220px), collapsed via --projax-sidebar-collapsed-width (56px). html[data-sidebar-collapsed="true"] flips between them with a 200 ms ease transition.
• Three sections: brand → nav (Tree / Dashboard / Calendar / Timeline / Graph / Admin, each an inline SVG + label) → bottom (theme toggle + sign-out + collapse toggle).
• Active item is marked server-side: layout.tmpl compares .Path (injected by web/server.go render() from r.URL.Path) against each item's href and emits class="nav-item active" on match. No JS needed for the active marker.
• Collapse toggle persists state in localStorage["projax.sidebar.collapsed"]. A pre-paint <script> block in <head> restores the attribute on <html> before first paint so the main-content margin doesn't flash 220 px → 56 px on every navigation. ~15 lines of vanilla JS, no framework.
• main.projax-main carries margin-left: var(--projax-sidebar-width) so content lives to the right of the sidebar. The transition matches the sidebar's so they move in sync.

Mobile (≤767px) — fixed-bottom <nav class="projax-bottom-nav"> with five slots:

• Tree / Dashboard / [+ New] center raised circle / Calendar / Menu.
• Center "+ New" is a 44×44 px raised circle with margin-top: -10px (mBrian's capture-button pattern) but points at /new because projax has no separate capture flow.
• "Menu" is a <details> element with <summary> styled as the bottom-nav-item. Tapping pops a small absolute-positioned drawer-sheet 8 px above the bottom-nav with the overflow items (Timeline, Graph, Admin, Theme toggle, Sign out). Default browser <details> toggle handles open/close + tap-outside-dismiss — no JS, no gesture wiring.
• Height = calc(56px + env(safe-area-inset-bottom, 0px)) and padding-bottom: env(safe-area-inset-bottom) so the iOS PWA install doesn't put the nav under the home indicator. Main content gets padding-bottom: calc(56px + 1rem + env(safe-area-inset-bottom)) so rows aren't hidden under the nav.
• Sidebar is display: none at this breakpoint; bottom-nav is display: none at ≥768px. Single surface visible at a time.

Theme toggle — same handler binds to both the sidebar button (#theme-toggle) and the drawer button (#theme-toggle-drawer); either surface flips data-theme on <html> and writes the projax_theme cookie. Existing Phase 4b semantics preserved exactly; only the button location changes.

What was deliberately parked:

• mBrian's sidebar resize handle. Their Sidebar.svelte has a $effect-feedback bug they spent a debug session on (see mBrian docs/sidebar-resize-debug.md). Static 220 / 56 px is sufficient — revisit only if multiple users push for it.
• Quick-capture modal (mBrian's center circle opens an in-app capture sheet). projax's "+ New" is just a link to /new.
• Quick-switcher / saved-searches / Today / Work / Quick-log slots from mBrian — none have analogues in projax. The 5-slot bottom-nav stays scoped to projax's actual surfaces.
• Drawer slide-up gesture. <details> with a CSS transform: translateY(8px) → 0 keyframe is enough for v1; a real bottom-sheet gesture is v2 polish.

19. Dashboard overhaul: Tiles + view switcher (Phase 5h)

The Phase 3e task-centric stream (5 cards: Open tasks / Events / Open issues / Recent docs / Stale) ships unchanged on the new Tasks tab. The default landing surface at /dashboard flips to a project-centric Tiles view per m's request "easily show a helpful overview over my current projects". Design plan: docs/plans/dashboard-overhaul.md (Phase A: 3 candidates surveyed, Tiles greenlit).

URL contract — defaults elide:

Param	Values	Default	Notes
view	tiles | tasks | events	tiles	Tab strip lives below the filter bar
scope	current | all	current	Tiles-only chip; Tasks + Events ignore it
tag / mgmt / has / q / status / public	(unchanged)	—	Same TreeFilter vocabulary as /, /timeline, /calendar, /graph
refresh	1	—	Busts the current (filter, view, scope) cache slot

Unknown view= values fall back to tiles.

Per-project rollup (dashboardProject) — one row per item.ID across every signal source. Built from the same aggregator rows the existing cards consume, so adding Tiles costs zero extra DAV/Gitea calls:

• OpenTasks — open VTODOs across every linked calendar (uncapped, unlike the 30-row Tasks card).
• Overdue — subset of OpenTasks with Due < startOfDay(now).
• OpenIssues — open Gitea issues across every linked repo (uncapped).
• LastActivity — max(repo.updated_at, latest VTODO LastModified, latest event start, latest dated link, latest issue UpdatedAt). Zero when no signal is seen.
• NextSignal / NextSignalKind — soonest-due open VTODO summary (kind=task); falls back to the latest-updated issue title (kind=issue) when no task; empty otherwise. Task wins over issue.
• IsLive — derived from Item.PublicLiveURL being non-empty.
• Stale — fed by the existing collectStale set so the rollup doesn't re-probe Gitea.

Sort: pinned first, then by primary path ascending.

IsCurrent(now) rule — Pinned OR OpenTasks > 0 OR OpenIssues > 0 OR LastActivity within 14d (dashboardActivityWindow). Drives the Current/Quiet split when scope=current.

Tiles layout — CSS grid minmax(0, 1fr) columns at 1/2/3 cols (≤600 / 600–900 / ≥900 px). Each tile:

• Star toggle (POST /dashboard/pin with id + pin=true|false) — flips Item.Pinned, invalidates the dashboard cache, re-renders the section. Star glyph is ☆ unpinned, ★ pinned.
• Title → /i/<path>, primary path under (mono font), optional live badge for IsLive, optional stale badge for Stale.
• Counts row: N open / M! (overdue, red) / K issues / quiet fallback.
• NextSignal one-liner with • (task) or ◆ (issue) marker; ellipsis on overflow.
• LastActivity stamp in the footer: now / Nm / Nh / Nd (see activityRel). Distinct from relativeTime so the narrow tile column reads cleanly.

minmax(0, 1fr) + min-width: 0 on .tile + overflow-wrap: anywhere on .tile-path are the canonical CSS-grid containment recipe — without all three, a long unbreakable slug-path or task summary widens its column past the viewport and forces a horizontal scroll. The hotfix that introduced this triad landed mid-rollout after m flagged the scroll.

Quiet (N) ▾ fold — <details> element below the primary grid containing every rollup with IsCurrent=false, including all stale candidates. Summary line: Quiet (N) — older than 14d · M stale (the stale count omits when zero). Tiles inside render with the same shape, slightly faded; stale tiles add a tile-stale class (dashed border) and a stale flag badge. The Quiet fold replaces the standalone Stale card from Phase 3e — m's pick: per-tile LastActivity stamp carries the staleness signal, "consider archiving?" framing migrates to the fold.

Scope chip — renders on the Tiles tab only (◇ current ⇄ ○ all). Tasks + Events tabs have no scope concept. The chip href flips between ?scope=all and the default URL, preserving the active view + filter.

Tasks tab — today's 5-card layout MINUS the Stale card. Inline VTODO writeback (/dashboard/task/done|edit|delete) stays exactly as Phase 3e wired it.

Events tab — promoted from the Tasks-tab Events card to its own surface with: top summary header N events · next 7 days, three-column day headings (relative label / ISO date / right-aligned count), and an empty-state copy inviting the user to link a CalDAV calendar from a project detail page. Same aggregate.Aggregator.Events source as the cards-tab version.

Cache — composes (filter | view=X | scope=Y) so each surface has its own 60s TTL slot. Pin flip calls InvalidateAll (Pinned affects sort order across every combination).

Mobile (≤768px) — tab strip wraps; scope chip drops to its own row centered. Tile padding tightens; pin button has a 36 px touch target (intentionally less than the 44 px elsewhere to keep the header row balanced), live badge has 32 px, Quiet fold summary has 12 px vertical padding. Events tab day-heading wraps; count drops below the label + date.

What was deliberately parked for a later phase:

• Activity tab (chronological feed of commits/issues/completions/docs) — m's pick was 3 tabs at launch, defer Activity to v2.
• Sortable Project Rows view (Candidate B from the design plan) — Tiles + Tasks tabs cover both daily-driver and detailed read-out shapes.
• Project filter dimension on TreeFilter and saved views — those are Phase 5i (parallel design with kahn).
• Anything that would need new MCP tools or schema columns — Pinned already existed and that was the only mutation needed.

10. References

• Project CLAUDE.md (this repo) — purpose, constraints, gated worker flow
• ~/.claude/CLAUDE.md — global conventions (memory, channel routing, git strategy)
• docs/plans/dashboard-overhaul.md — Phase 5h design plan (3 candidates + recommendation + m's chip picks)
• mai.projects schema (msupabase) — current state being adapted
• mBrian nodes/edges schema — terminology source
• otto session 2026-05-15 — inventory motivating this project