agent parallelism: background tools, bg spawn_agent, parallel tool batches, message queue ...

- backgroundable tools (terminal/ssh_exec/peer/spawn_agent/code_exec) detach
  via TaskManager with per-session/global/spawn caps, rate limit and TTL
- completion delivery both ways: task_update event (out-of-band) + pending
  notes injected into the next turn; tasks tool (list/check/wait/cancel)
- parallel tool-call batches (profile-level gate, off by default) with
  ToolStarted up-front, tagged event mux, call-order results, one save,
  plus dangling tool_call repair on session load
- user message queue instead of busy error: message_queued frame,
  back-to-back drain on the same socket, headless fallback on disconnect
- pin mcp<2 (v2 renames FastMCP with breaking API changes)
- docs: tasks.md (new), websocket/api/agent/config updates, tasks manual,
  spawn_agent background param, persona contract section

PWA: installable webclient, offline shell, web push ...

Installability:
- public/manifest.webmanifest (standalone, theme #16161E) + PNG icons
  generated from logo.svg (regular + maskable, served via /images mount)
- index.html: manifest link, theme-color, apple-touch-icon

Offline shell:
- hand-rolled sw.js (no workbox): navigation = network-first (3s race)
  with cached-shell fallback + background refresh (a stale cached shell
  would 404 on entry chunks after a deploy); /assets/* cache-first
  (content-hashed); /images/* cache-first capped; /api,/ws,/auth,/push,
  /content pass-through
- vite closeBundle plugin stamps __NAVI_BUILD_VERSION__ (digest of
  index.html + asset names) into dist/sw.js; sw.js served no-store so
  every deploy reactivates the SW and activation evicts old caches
- SW registration in main.js, PROD only (dev HMR untouched)
- OfflineBanner (useOnline composable) over the app shell

Web push (VAPID, pywebpush):
- navi/push/ package: push_subscriptions table (postgres, boot-time DDL),
  PushSubscriptionStore, PushService (async fan-out, to_thread sends,
  404/410 prunes dead endpoints, per-session cooldown)
- routes: GET /push/vapid-key, POST/DELETE /push/subscribe (auth-gated)
- trigger in orchestrator run_agent + run_recall: push on StreamEnd when
  no WebSocket client watches the session; fire-and-forget, never
  disturbs the run; anonymous fallback only when auth is off
- client: usePush composable + Notifications settings panel (enable/
  disable via PushManager.subscribe with the server VAPID key)
- notification click focuses the app at /#<session_id> (hash routing
  opens the right chat); payload body is a markdown-stripped <=140-char
  preview

NAVIVAPID keys empty = push fully disabled (graceful, like other optional
integrations). dist/ artifacts committed per repo convention.

Tests: pytest push store/service/routes/trigger (+23), vitest usePush
(83 webclient tests green). Full suite 1143 passed.

swarm stage 1: instance identity, PSK, hive registry, announce loop ...

- navi/identity.py: adjective-animal names + uuid in instance.json
  (generated at install, renameable by hand)
- navi/swarm.py: HiveAnnouncer - periodic POST /announce to the hive
  with non-blocking reachability tracking (transitional logs, /health
  export, hive_status context provider reports outages to the agent)
- hive/: standalone FastAPI address book (SQLite, port 8087, PSK via
  X-Swarm-Key with .swarm-key.previous rotation window, TTL online
  status, host from client IP, port from payload). Not installed or
  started by default - run manually on the main server.
- ports moved to 8099 (API) / 8098 (UI MCP)
- install.sh: PYTHONIOENCODING=utf-8 in the systemd unit, generates
  instance.json and .swarm-key on fresh installs

port: 8000/8001 -> 8099/8098 everywhere ...

navi runs on shared servers where 8000/8001 are usually taken. New
defaults: API 8099, navi_ui MCP 8098. Touched: config defaults
(navi_port, navi_ui_mcp_port, public_url, gnauth_redirect_uri),
navi-server launcher docs, env.template/.env.example, install.sh
health-check fallback, terminal client base_url, webclient dev configs
(useWebSocket, contentLinks, vite proxy), android url hint, docs.
Also made the navi_ui FastMCP constructor port settings-driven instead
of a hardcoded 8001 (it was overridden at start anyway).

deploy: one-command server bundle (dockerized postgres + systemd) ...

deploy/install.sh — everything in one command: prerequisite checks,
.env provisioning from env.template (generated DB password), dockerized
PostgreSQL (pgvector image, restart: always, bound to 127.0.0.1, vector
+ pg_trgm extensions), venv + pip install, a systemd unit with
Restart=always (the server lives from installation, per the roadmap
where these modules become each other's subagents), health check, and
navi-code/navi-server symlinks into PATH. Idempotent — safe to re-run.

Default deployed shape: web UI off, auth off, terminal client only.
Re-enabling the web panel later is editing .env + restart — nothing is
removed from the tree.

The deploy branch (next commit set) differs from master only by a
filled-in .env.

permissions: remove broken client-side gate; add backend design doc ...

The terminal-TUI permission gate was a race: _execute_tools_with_sink
emits ToolStarted and starts the tool on the backend immediately, so by
the time the client dialog appeared the destructive action had already
run -- 'deny' could only stop the session, not un-execute the tool. It
also existed only in the terminal TUI (webclient/android had nothing),
and the system-prompt 'Strict Confirmation' nudge was an unreliable
duplicate.

Remove the broken machinery for a clean slate and plan the real
replacement from zero:

- delete clients/terminal/tui/permissions.py, screens/permission_dialog.py
  and their tests
- strip tui_app.py (engine, _deny_tool, _show_permission_dialog,
  _confirm_shell_command, _stop_session_worker, on_permission_request,
  tool_started gate) and the PermissionRequest TUI event; !cmd now runs
  directly (user-typed, no agent gate)
- drop the 'Strict Confirmation' prompt rule from navi_code/developer/
  tool_developer
- add docs/permissions.md: authoritative backend gate design (engine +
  registry + event + endpoint + agent gate + postgres policy + global
  rules config, sub-agents gated) -- design only, not yet implemented
- update docs/index.md, navi_code_cli.md, profiles.md, testing.md

Until Phase 1 lands there is no destructive-action confirmation -- a
conscious period without the false security of the old race-gate.

docs: index, profiles, tools, api actualization + archive historical docs ...

index.md: expand the file map to reference navi_code, navi_code_cli, store,
context_providers, eval_system, android-client, testing; point at archive/
for historical notes.

profiles.md: add the Compression section (compression_keep_recent /
compression_max_tokens / compression_prompt_file overrides), the
subagent_system_prompt field, and a note that AgentProfile allows unknown
keys (model_config extra=allow).

tools.md: rewrite the user-tools self-extension section — write_tool is
deprecated and removed; write the file via filesystem/code_exec and call
reload_tools instead.

api.md: add missing REST endpoints (GET /sessions/{id}/todos, GET
/sessions/{id}/files list, GET /sessions/{id}/messages/archive, POST
/sessions/{id}/stop) and the admin MCP management block (config CRUD,
reconnect, status, test, profile-mcp mapping, admin recalls); fix the
WS client→server table (type: message|compact, image limits 8/50MB);
add model_info / todo_updated / compression_started events; fix
recall_update action (add skipped), session_sync payload, context_compressed
threshold (70%).

Archive: move plan_01_god_object_agent.md, tech_debt_review_2026-04-29.md,
architecture_weak_spots.md, future_headless_nodes.md into docs/archive/
(historical design notes, no inbound links).

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

docs: update docs for tools.agent/tools.subagent and Navi Code TUI ...

- profiles.md: document tools.agent/tools.subagent structure, deprecate enabled_tools
- tools.md: move web tools to MCP section, fix mcp__navi-web__* names, add create_mcp_server/test_mcp_tool/mcp_status/recall tools
- api.md: update /agents/profiles and /admin/profiles/{id} response schemas, fix MCP examples
- navi_code.md: correct navi_code tool list (MCP disabled)
- navi_code_cli.md: add /thinking, /compact, correct TUI layout
- index.md: add navi_code, terminal client, pydantic-settings
- testing.md: refresh test directory layout, replace stale coverage roadmap
- agent.md: mention tools.agent/tools.subagent in loop

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

Add NAVI_AUTH_ENABLED switch for optional auth ...

- Add navi_auth_enabled setting (default true) to navi/config.py and .env.example
- When disabled, treat every request as anonymous admin user (id='anonymous')
- Create/update fixed anonymous navi_users row on startup
- Bypass OAuth/cookie/API-token resolution in navi/auth/deps.py
- Update /auth/status to return {enabled, configured}
- Log security warning on startup when auth is disabled
- Update webclient: skip fetchMe/login screen, show Local mode footer,
  expose /admin link, warn in API keys panel
- Rebuild webclient production bundle
- Add unit and integration tests for no-auth mode
- Update docs: auth.md, config.md, api.md, api_tokens.md, sessions.md,
  websocket.md, mechanics.md, index.md

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

Fix settings route switching and document API token system ...

- App.vue: make route reactive via ref + getRouteFromHash() so
  #settings toggles work without page reload
- docs/api_tokens.md: new comprehensive API token auth doc
- docs/api.md: add /api-tokens REST endpoints
- docs/auth.md: add token flow architecture diagram and resolution order
- docs/websocket.md: add auth section with cookie vs query-param token
- docs/architecture.md: update to AgentSessionOrchestrator + ToolContext
- docs/tools.md: add gnexus-creds MCP tools
- docs/index.md: link to api_tokens.md
- Rebuild webclient dist

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

Add comprehensive mechanics catalog (docs/mechanics.md) ...

Master catalog of all mechanisms in the Navi project:
- 80+ mechanics catalogued across all subsystems
- Each with description, config flags, source files, documentation status
- 50 undocumented mechanics explicitly listed
- Cross-reference index for feature planning
- Updated docs/index.md to link the catalog

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

docs: document scheduled recall system ...

- Add docs/recall.md with full architecture, data model, tools, loop behavior
- Update docs/api.md with recall endpoints (GET/DELETE/POST recall) and recall_update WS event
- Update docs/websocket.md with recall_update frame and session_sync case #3
- Update docs/tools.md: add ScheduleRecallTool and ManageRecallTool
- Update docs/sessions.md: add is_recall message flag
- Update docs/index.md: link recall.md in file map

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

Document multi-user auth system ...

- New docs/auth.md — comprehensive auth guide: OAuth flow, roles/permissions,
  webhooks, env vars, setup instructions, API reference, WebSocket auth,
  testing with mocked auth
- Update docs/config.md — add gnexus-auth OAuth env vars table
- Update docs/api.md — add /auth/*, /admin/*, /webhooks/gnexus-auth endpoints
- Update docs/index.md — add auth.md to file map
- Update docs/sessions.md — document user_id column and list_all filtering
- Update docs/memory.md — document user_id scoping in facts and summaries

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

Clean up SQLite references in docs and prompts after removal ...

- docs/index.md: PostgreSQL via asyncpg
- docs/memory.md: drop aiosqlite fallback mention
- docs/sessions.md: replace SqliteSessionStore with PgSessionStore docs
- webclient/docs/architecture.md: PostgreSQL only
- navi/profiles/tool_developer/system_prompt.txt: remove aiosqlite from available imports
- .gitignore: add .codex and *.db
- No remaining sqlite/aiosqlite/db_path references in codebase

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

Use gemma4 cloud model by default

Comprehensive documentation update ...

- websocket.md: add heartbeat, session_sync, replay_start/end, planning_status,
  plan_ready (with is_subagent), stream_end extra fields, context_compressed summary,
  updated _AgentRun.events replay buffer, corrected reconnect section
- sessions.md: add name, planning_logs fields; message flags (is_plan, is_compression,
  is_summary, thinking); set_name store op; debug endpoints section
- api.md: full rewrite — add generate-name, planning, file download endpoints;
  all missing WS events; correct message field table with is_plan/is_compression
- tools.md: update user tools list with all current tools
- index.md: fix profiles list (smart_home → developer)
- CLAUDE.md: add Documentation section with table of all docs files
- NAVI.md: add architecture.md entry, improve websocket description

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

Add backend documentation ...

10 markdown files covering all backend subsystems: architecture,
agent loop, tool system, sessions, WebSocket protocol, profiles,
memory, config, and API reference. Structured for AI readability
with a single entry point (docs/index.md) and cross-references.

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