# Codex implementation task

## Outcome

Turn the included Private Assistant UI into Jimmi's local assistant, using existing **self-hosted Appwrite 1.9.6** and **Hermes Agent**, while retaining the ability to replace Hermes through an adapter. Return research/build files as authenticated Open and Download actions in the same chat. Normal use must feel like one chat, without model or harness choices in the composer.

This kit is derived from Site v3, source commit `94d7e3c4210281b58259e30837bd0894005a8ba7`. It is an independent export; do not create a Sites project or deploy back to the public prototype. `docs/original-design-brief.md` is historical UX background. This file and `docs/IMPLEMENTATION.md` supersede its PostgreSQL/NATS/MinIO stack suggestions.

## Known setup and facts to verify

- Arc B580 12 GB: conversational coordinator, currently Qwen3.5 9B Q6 in the conversation context.
- RX 7900 XTX 24 GB: Qwen3.8 27B research/reasoning and a replaceable coding model such as Ornith 1.5. The names are user-provided identifiers, not proof of exact runtime model IDs or fit.
- CometOS/Ubuntu is associated with the Arc; Unraid Tower with the XTX. Discover actual reachable hosts and current service configuration before edits. Do not rely on old IPs or model examples.
- Hermes agents/profiles already exist. Preserve their workspaces, memory and credentials; integrate through a dedicated verified profile or the appropriate existing service.
- Treat approximately 65k context as a requested compatibility target to measure per role/model. Do not assume it fits the Arc merely because a model advertises that context. Record effective context, KV memory, quantization and concurrency limits.
- Immich ML shares constrained resources. Preserve existing photo jobs; CPU fallback requires explicitly configured compatible ML service routing, not a UI toggle alone.
- Existing Appwrite 1.9.6, proxy and operator tools should be reused. Confirm endpoints, project, TLS, authentication, service versions, allowed deployment scope and secret access.

## Execution order

1. Read AGENTS.md, docs/IMPLEMENTATION.md, docs/ACCEPTANCE.md and docs/SOURCES.md. Run local checks before editing. Inventory installed services and confirm version/capability reports using read-only probes. Report only missing information that blocks actual implementation.
2. Create an isolated application project/database/bucket on the existing Appwrite instance, or use a specifically assigned empty project. Review the bootstrap dry run. The apply script is additive and is not an upgrade or backup tool.
3. Build an authenticated vertical slice: sign in through Appwrite; create a conversation and user message; submit one chat run to the verified Hermes adapter; stream the reply; persist it; reload and see the same history. Enforce ownership before every server-key operation.
4. Add server-owned background runs, replayable progress events and private Appwrite Storage artifacts with Open/Download. A closed browser must not cancel work. Put model inference behind the independent route/gateway contract.
5. Replace simulated functions in the existing UI one boundary at a time. Implement durable harness and model registries; pin accepted runs to config revisions. Stop timer-driven fake progress and demo seed jobs in production.
6. Implement the singleton scheduler and physical worker lease protocol against fake workers first. Then connect the Arc and XTX model runtimes. Keep chat resident; checkpoint/cancel safely before exclusive XTX swaps. Never use a harness change as a shortcut around a GPU lease.
7. Integrate Immich using its installed release's supported endpoints, queues and execution providers. Begin with a manually verified idle-only or CPU service policy. Add automated yield/resume only after proving no duplicate or lost work.
8. Validate critical failure/ownership/race cases in docs/ACCEPTANCE.md. Prepare an existing-proxy deployment and rollback procedure; report which checks have passed and which require hardware. Deploy only within the user's authorized environment and scope.

## Deliverables from the implementing Codex

- Working UI and authenticated API/worker, same visual design, with simulation clearly separated.
- Versioned Appwrite schema and migration notes; verified Hermes release/transport/configuration; pinned dependencies/images for the deployment actually used.
- Environment examples without credentials, service definitions, health checks and backup/rollback instructions.
- Tests covering ownership, durable jobs, model/harness switching, duplicate events/side effects, artifact delivery and worker restart.
- A short operator runbook with real service URLs and commands, with secrets excluded.

Do not stop after another architecture proposal. Implement the next concrete slice that the available access permits. If access is missing, complete local code and tests and give one precise request for the missing endpoint/credential reference; never ask the user to paste secrets into a public document.