claude-mds/officer.dev/CLAUDE.md

CLAUDE.md — officer.dev workspace root

This is the working root for developing Officer: authoring capabilities and making platform changes that support them. Sessions started in this cwd are for exactly that loop — write/fix a capability, and when it needs platform support, fix the platform too.

You (Claude) are a standing collaborator here. The owner spins up new chats from this cwd to build capabilities and correct the platform. Assume that recurring intent. Be proactive about the runtime facts below — most wasted time in past sessions came from forgetting them.

Layout (root is NOT a git repo; the two subdirs are)

officer.dev/
├── platform/       # the Officer app — one Bun process. Git repo. See platform/CLAUDE.md
├── capabilities/   # OFFICER_ITEMS_DIR — file-based store of items. Git repo. See capabilities/CLAUDE.md
├── data/           # DATA_PATH — managed homes, attachments, job logs (data/jobs/<id>.log)
└── (marketplace/, mobile-apps/, Lyrics/, DOCS/, … — not usually in scope)

Read platform/CLAUDE.md and capabilities/CLAUDE.md — they are authoritative for their subtrees. This file captures the cross-cutting operational reality that neither of those spells out.

Runtime facts that WILL bite you (learned the hard way)

• The server runs via PM2 as bun start — production, NO --watch. Process officer (NODE_ENV=production bun src/server.tsx). So platform TypeScript changes do NOT hot-reload. After editing anything under platform/src (backend or frontend), it needs a pm2 restart officer to take effect. Forgetting this looks exactly like "my fix didn't work." Confirm the reload before diagnosing further.

  • Run the restart yourself, and say that you did. This said "NEVER run pm2 yourself" until 2026-08-20. The owner granted the opposite on this machine: restart when a change needs it rather than handing over a command to paste. What did NOT change is the scope — restart ONLY the process(es) the change needs (for platform TS edits that is pm2 restart officer alone, never the whole ecosystem.config.cjs, which bounces every sidecar).
  • Check who else is live first. The owner edits the platform using the platform, and often has several sessions open, so a restart can cut another agent off mid-turn or bounce the process you are both running inside. Look at pm2 list, the session list, the process table. Restarting is also the one moment a half-applied change from a shared checkout ships — confirm the tree is coherent (typecheck clean, database schema matching the code) before you bounce anything.

• Capabilities ARE hot — no restart. Files under capabilities/ are re-read from disk on each run / request (Pi per agent session, the app per request). Edit TASK.md / index.ts / categories.yaml and it's live immediately. This asymmetry is the #1 source of confusion: the capability change shows up, the platform change doesn't, and it looks like a partial failure.

• Frontend is served bundled from index.gen.html (platform/src/apps/officer-web/index.gen.html, imported by src/server.tsx, regenerated by platform/scripts/gen-index.ts at boot). After a platform restart the browser can still hold a stale JS bundle → do a hard refresh (Ctrl/Cmd-Shift-R). "Backend correct but UI unchanged" is almost always this.

• React Query caches tasks / task-categories with staleTime: 60_000. Menu/category changes lag up to a minute or until the view remounts. Hard refresh forces it.

• pm2 restart officer no longer kills the agent session. Fixed and merged on 2026-07-30; verified running. The agent is its own PM2 peer (officer-agent) and the Anthropic proxy is honestly named (officer-anthropic-proxy) — they were one misnamed entry, officer-claude, which is how the old claim in this file ("restarting officer doesn't disturb the agent") was both wrong and believed: the process that runs claude was spawned by the main server, so PM2's tree-kill took it down every time. A restart now costs the agent a socket reconnect, not the session, and output produced while officer is down survives — the sidecar writes to chat_session_events itself. There is no officer-claude.

• Officer is TWENTY-SIX PM2 entries here today (verified 2026-08-27 by bun run docs:check, which fails if this drifts): the five core processes — officer, officer-anthropic-proxy, officer-claude-code, officer-opencode, officer-pty — plus officer-notify, officer-marketplace, officer-oas, and one per installed plugin.

  It was thirteen this morning. Nothing about the platform changed: all 21 plugins were installed on this machine so the marketplace UI had something real to render. That is the paragraph below working exactly as written, not an exception to it.

  It was fifteen on 2026-08-25; officer-minesweeper and officer-transcribe were uninstalled since, which is the point of the paragraph below rather than an exception to it.

  This number tracks PLUGIN INSTALLS, not platform releases. It went to fourteen when Minesweeper was installed and back to thirteen when it was removed, with no platform change either time — installing a plugin that declares a sidecar writes it into the generated ecosystem file. Do not read a change here as a platform change, and do not expect two machines to agree.

  It said "twenty" and listed a different set until 2026-08-23 — including officer-vault, officer-slskd, officer-headscale, officer-transmission, officer-invoiceshelf, officer-wallet, officer-photos, officer-jellyfin, officer-gitea, officer-music, officer-vnc, none of which run here, while omitting six that do. That is what a hand-maintained list of processes becomes: accurate on 2026-08-07, and nobody re-derives a list while editing the sentence around it. mybiblepal-api and mybiblepal-audio are also gone; nothing shares this daemon today.

  Never pm2 restart ecosystem.config.cjs — it bounces every sidecar. Use --only <name>, or restart the single process the change needs. pm2 jlist is still the source of truth; the check exists so the copy cannot silently stop matching it.

• OFFICER_ITEMS_DIR=/home/pastilhas/dockers/officer.dev/capabilities ← items live here

• DATA_PATH=/home/pastilhas/dockers/officer.dev/data

• HOME_DIR=/home/pastilhas and HOME=/home/pastilhas — equal here (matters for ~ expansion). getOwnerHomeDir(email) = process.env.HOME_DIR ?? DATA_PATH/<email>/home. Where task runs actually execute = getOwnerHomeDir (the real login home), NOT the managed getHomeDir.

• POSTGRES_URL=postgresql://postgres:postgres@127.0.0.1:5432/officer_dev (single DB, Drizzle). Schema changes: edit schema code → bun db:push (no migrations, no __drizzle_migrations). Multi-column uniqueness is declared with uniqueIndex, never unique().on(...) — drizzle-kit mis-diffs named composite unique constraints and re-creates them on every push, which used to stop db:push on an unanswerable truncate prompt. Rules in platform/src/databases/CLAUDE.md → "Composite keys".

• Typecheck with bunx tsgo (not tsc). Keep it clean.

• Installs are frozen. bunfig.toml sets [install] frozenLockfile = true in platform/ and monorepo-mobile/, so bun install resolves from bun.lock and fails rather than picking up a version nobody chose. Changing a dependency means bun install --no-frozen-lockfile deliberately, reading the lockfile diff, and committing it. Never add that flag to a script or CI to silence the error. Full reasoning — and the 2026-08-04 npm compromise that prompted it — in platform/CLAUDE.md → "Installs are frozen".

Task-runner data flow (script mode) — the mental model

File browser right-click → TaskRunnerDialog → TaskRunnerModal:

• cwd = { root:'home', path: currentPath-without-leading-slash } — the folder the browser is showing (parent of the clicked entry).
• entryName = the clicked entry; entry_path autofill = ~/<cwd.path>/<entryName> (tilde form).
• For a directory trigger, the ScriptRunner must descend into the entry: cwd = cwd.path ? ${cwd.path}/${entryName} : entryName (mirrors Pipeline/Agentic runners).
• POST /jobs {taskDirName, inputs, cwd, action} → job row in pipeline_jobs.
• execute-script.ts: cwd resolved as isAbsolute(cwd) ? cwd : join(getOwnerHomeDir, cwd) — so cwd must be home-relative WITHOUT a leading slash. Inputs passed BOTH as positional args (in task.args order) and as INPUT_<NAME> env vars (uppercased). Runs bun run index.ts in a temp dir — only index.ts is materialized, so script tasks must be fully self-contained (no sibling imports).
• inline tri-state on the task: false/absent = background job; true = ephemeral modal; 'ask' = modal offers the choice.

Jobs view architecture

• pipeline_jobs.mode is a TS-only enum ('pipeline' | 'script' | 'agentic') — no DB CHECK.
• JobDetailPanel fetches GET /jobs/:id, reads mode, dispatches: script → ScriptJobDetail, download → DownloadJobDetail (legacy history), else PipelineJobDetail.
• GET /jobs/:id returns the whole row (db.select().from(pipelineJobs) → includes progress).
• Progress protocol: a script prints @@officer:progress@@ {json} lines. execute-script's pumpStdout line-buffers stdout, plucks those lines out (→ progress events, NOT written to the .log), and passes everything else through to data/jobs/<id>.log. The job manager persists the latest progress to the progress column (periodic flush, PROGRESS_FLUSH_MS = 3000). ScriptJobDetail renders PhaseBars when progress has {meta, dl} shape (isDownloadProgress).
• The persisted .log is the human narration; the bars come from the sentinel. Keep those two channels separate — never let sentinels leak into the log.
• killTree: Stop → SIGTERM the process tree, SIGKILL after ~2s grace → scripts can cooperatively abort on SIGTERM/SIGINT.

Frontend navigation — the URL is the source of truth

Before building or changing any screen that selects something, read platform/docs/navigation-audit.md. It is the authority, and the rules it sets are easy to violate by accident because most of the existing app predates it:

• Selection state lives in the URL (useParams / useSearchParams), not in a usePanelChannel or useGlobal channel. Channels are for refresh/signal buses only.
• Rows are real <Link>s; nav chrome uses react-router's <NavLink> so active state comes from the router instead of hand-rolled JS. src/workspaces/components/NavLink.tsx is a different thing — a <Link> wrapper that carries the global query string, with no active state.
• Screens come in route pairs (/x + /x/:param) with a single <Navigate … replace /> guard. A master list with a live preview uses ?selected=<id>, because the detail route is the full page.

Full rationale and the per-case detail are in platform/CLAUDE.md → "Frontend route conventions".

Reference capability: download-media (the worked example)

Script task (mode: script, language: typescript, inline: ask, directory trigger, category: Media). Talks directly to self-hosted ReClip (its own yt-dlp) at RECLIP_URL (default http://localhost:8899): POST /api/playlist, /api/info, /api/download {url,format,title} →{job_id}, GET /api/status/{job_id}, /api/file/{job_id}. Titles are mandatory — ReClip names the output file from the title sent (empty title → hash filename), which is why Phase 1 fetches metadata before downloading. Two phases (metadata → download), per-item failures skipped not fatal, description sidecars next to each file. Mix/radio playlists (list=RD…) return a different set each call, so the download panel pre-expands to individual video URLs and the task passes those through untouched.

• resolveDestDir(): honours an absolute INPUT_PATH, including the ~/… autofill form (expanded against $HOME); otherwise falls back to process.cwd() (which the platform sets to the target folder). Relative paths are ignored (would double-resolve).

Category ordering

capabilities/categories.yaml is a plain ordered list; a task joins a category via its TASK.md category: field. Add a category = one line here + the tasks that use it, no code change. Unlisted categories sort alphabetically after listed ones; no category → "Other" (always last).

State of play (2026-08-07)

Multi-user is the current direction, and it is half-built. On 2026-08-07 a capability permission model landed in platform/src/servers/capabilities/: registry.ts enumerates every capability in four kinds (core / app / execution / admin), authorize.ts resolves them per request, and totality.ts makes the server refuse to boot if a mounted router has no registry entry. Grants are keyed on role, never on a user, and live in role_capabilities; absence denies. execution capabilities (terminal, chat, files, tasks, items, desktop, browser) run as the owner's OS user in the owner's home and are never grantable at any level — that is structural, not a policy default.

Account creation now exists — POST /api/users, owner-gated, with a form under Settings → User Management, plus role change, password reset, Linux provisioning and delete. It landed in 69a31051; this file claimed the opposite for days afterwards, and so did platform/CLAUDE.md and docs/roles-and-teams.md, which sequenced a phase around building the thing that already existed.

Roles are a table as of 2026-08-23, with users.role and role_permissions.role as foreign keys onto roles.name with ON UPDATE CASCADE. USER_ROLES is gone and UserRole is string, so the guard the compiler used to provide is now a runtime check at every write path that takes a role from outside.

The design write-up is COMMS/capability-permissions-2026-08-07.md; the roles plan and what is still open is docs/roles-and-teams.md.

The single-user claims that used to be all over this repo's docs were corrected on 2026-08-07. If you find another one, it is stale — platform/src/servers/capabilities/registry.ts is the authority.

Both repos are clean and pushed — platform to gitea and origin, capabilities to gitea only (deliberately; never rezio). The sidecar isolation work and the navigation refactor are merged and runtime-tested (41-check pass; the checklist was spent and deleted). Every sidecars-* branch and navigation-refactor is deleted — merged, nothing stranded.

Jellyfin is the newest capability (officer-jellyfin, /jellyfin): server registry with the access token write-only across the boundary, browse/detail/search, and a player with three transports — direct file, HLS over a vendored hls.js, and a progressive fallback. Two things there are worth knowing before touching it. src/workspaces/officerdev/src/apps/Jellyfin/vendor/ holds hls.js as a committed, unminified file with its provenance hashes in a README beside it: that is the frozen-install rule applied to a library we genuinely need, and it is reformat-exempt in .prettierignore because the diff against upstream is the only thing that makes it reviewable. And useClient() rebuilds its verbs on every render — anything that puts one of them in a useCallback dependency list gets a new identity every render. That silently disabled every playback report in the Jellyfin player for days (an unmount cleanup re-running mid-playback); the fix is refs, and the same trap applies to any React Query mutation object.

Projects is gone. The feature was removed end to end on 2026-07-30 — screens, panel apps, routes, dock entry, the projects table and its proj-* keys in the dashboards endpoint. getUserProjectsDir in data-path.ts stays: the apps and dev-server routers resolve user apps under the same on-disk Projects/ directory and are unrelated. Nothing on disk was touched.

Sidecar work still outstanding, in rough order of size:

• claude stages 3–5 — invert the transport so the agent listens on its own port instead of dialling out, move the 361-line transcript reader in behind it, and survive a restart of the agent sidecar itself. Stages 0–2 (PM2 peer, durable turn output) are done and running. This is the last sidecar still driven by a typed command vocabulary over the registration socket.
• the terminal session-orphan leak — closing a panel for good leaves its shell running. Re-attach on reopen and a Running Shells panel landed, so an orphan is now visible and killable; what is missing is the panel system being able to tell a real close from an incidental unmount, which is what would let anything send pty:close automatically.
• slskd is largely compliant. The vault is off-limits.

Done since this list was written: email (store, routes, accounts, resync and both syncs now live in the sidecar, which schedules its own work and serves its own HTTP — the platform side is 22 lines), pty stage 4 (the bridge is a byte relay onto the sidecar's own listener; the pty command vocabulary is gone from the wire protocol), every HTTP sidecar moved onto the shared createSidecarProxy factory, and five new sidecars built to that shape from the start: photos, notify, caldav, memos, jellyfin.

Known and deliberately unfixed: on mobile, tapping edit on a dashboard opens the form in a panel you cannot see. The dashboard edit form is rendered into a panel that mobile layout never shows; mobile web is being retired in favour of a native app, so it is not worth the fix.

Test checklists live here, not in the repo

Working checklists for a migration in progress — what has been clicked through and what has not — belong in this directory, deliberately untracked. That is state about this machine at this moment, not something a clone of the repo should carry. When a migration is finished, delete its checklist; on 2026-08-08 ten spent ones went (~750 KB of nav, email, desktop and agent-status notes), and the only reason they had survived was that nobody was sure whether anything still pointed at them.

REVOKE-TOMORROW.md is the exception and must stay until the Discord and Telegram tokens it names are actually reset at the providers — it is the only record of which ones.

Working agreement

• Delegate the writing. When a feature is agreed and what remains is typing — a change repeated across many files, translations, a form, a migration over a list of call sites — hand it to a cheaper agent, keep working, and review the DIFF when it returns. The owner's architecture, somebody else's typing, your review in the middle. This is the default here, not a per-task decision, and it does not need asking for. Read capabilities/skills/delegating/SKILL.md before writing the brief: an agent that has to ask a question has already cost more than it saved. Pick the cheapest model that will get it right — Haiku for mechanical, Sonnet by default, Opus only when the work still holds a decision, which usually means the brief needs finishing rather than a bigger model. Do NOT delegate anything where a wrong guess is quiet and expensive — permission checks, credentials, anything that deletes — because reviewing those properly costs as much as writing them.
• Fix what you find. If a defect is diagnosed and you know the fix, apply it — don't stop to ask. The owner retests immediately and restarts cost nothing. Still ask when it's a genuine product decision rather than a defect, when it widens scope, or when it's hard to reverse.
• Explore related files before editing. Keep it simple, explicit, focused. Note unrelated problems, don't fix them uninvited.
• Report honestly — distinguish what you verified (filesystem, DB, logs) from what you assumed.
• When something "doesn't work," check the restart/cache asymmetry above BEFORE re-diagnosing code.
• A background timer must leave evidence, but only interrupt on action. Any recurring/detached job set up on the owner's behalf — a cron entry, a watcher, a poll loop — splits its reporting in two:
  • To the log, every tick, including no-ops. A fresh timestamp is the only thing that distinguishes "nothing to do" from "the timer died", and that question comes up. Cheap, silent, always on.
  • To the owner, only when the tick actually acted on something. Say what changed and what was done about it, unprompted. Never narrate a quiet tick at him — a heartbeat he has to read is noise. Current instance: auto-pull.sh + the * * * * * crontab entry, log at officer.dev/auto-pull.log.