yashturkar · christoaluckal · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026
diff --git a/docs/RELIABILITY.md b/docs/RELIABILITY.md
@@ -19,6 +19,8 @@ review_cycle_days: 21
 ## Service Expectations
 
 - `kb-server` readiness requires database and Git-backed vault access.
+- `/admin` should surface the same readiness blockers and recent operational signals visible through logs and DB-backed job/event tables.
+- The Streamlit dashboard should degrade cleanly when the FastAPI backend is offline and still allow operators to launch configured start commands.
 - Autosave worker should tolerate transient Git/network failures.
 - `vault-sync` should converge after temporary API outages.
 
@@ -31,6 +33,7 @@ review_cycle_days: 21
 ## Reliability Signals
 
 - API health and readiness checks.
+- Admin dashboard state for config source, readiness blockers, git state, pending batch paths, and PR visibility.
 - Job/event tables for write and publish operations.
 - Sync logs for pull/push loop success and retries.
 
@@ -39,15 +42,35 @@ review_cycle_days: 21
 ### DB outage (`kb-server`)
 
 - Signal: `GET /health` stays 200 while `GET /ready` returns non-200 with DB failure detail.
+- Signal: `/admin` shows DB not ready and surfaces the same readiness error.
 - Signal: API logs show database connection failures from readiness and write paths.
 - Recovery check: when DB is restored, `GET /ready` returns 200 without process restart.
 
 ### Git remote / GitHub outage (`kb-server`)
 
 - Signal: autosave or batcher logs show push/PR failures while local commits continue.
+- Signal: `/admin` PR summary shows GitHub/API errors or empty PR visibility despite queued/pushed work.
 - Signal: pending API changes remain on `kb-api/*` branch until push/PR succeeds.
 - Recovery check: retry loop or next batch cycle pushes and re-establishes PR state.
 
+### Config drift / restart-needed state (`kb-server`)
+
+- Signal: `/admin` shows updated `.env` values, but runtime behavior still reflects old DB/auth/process settings.
+- Cause: some settings are effectively startup-bound because the API process and worker initialize long-lived config or connections at startup.
+- Recovery check: restart `kb-api` and `kb-worker`, then confirm `/admin` and `/ready` reflect the expected state.
+
+### API offline but local dashboard available (`kb-server`)
+
+- Signal: Streamlit dashboard reports backend offline instead of crashing.
+- Cause: `kb-api` is down, misbound, or unreachable at the configured backend URL.
+- Recovery check: launch the derived tmux start command via the dashboard, rerun the dashboard, and confirm `/admin/api/state` responds again.
+
+### Autosave worker offline (`kb-server`)
+
+- Signal: Streamlit dashboard shows worker runtime config but autosave activity stops advancing.
+- Cause: `kb-worker` tmux session is down or was never started.
+- Recovery check: launch or restart the worker from the dashboard and confirm vault events resume.
+
 ### API outage (`vault-sync`)
 
 - Signal: sync loop logs pull/push request failures and keeps retrying on interval.

diff --git a/docs/SECURITY.md b/docs/SECURITY.md
@@ -18,13 +18,16 @@ review_cycle_days: 21
 ## Auth Boundary
 
 - API key auth is enforced by server middleware when configured (`KB_API_KEY` non-empty).
-- With auth enabled, all HTTP routes require `X-API-Key`, including `/health`, `/ready`, `/docs`, and `/openapi.json`.
+- With auth enabled, non-admin HTTP routes require `X-API-Key`, including `/health`, `/ready`, `/docs`, and `/openapi.json`.
+- `/admin` and `/admin/api/*` are intentionally exempt from `X-API-Key` so the local operator dashboard can bootstrap and operate the instance.
 - With auth disabled (`KB_API_KEY` empty), requests are accepted without API-key checks.
 - `KB_API_KEY` must never be committed in docs examples with live values.
 
 ## Secret Handling
 
-- Secrets remain in local `.env` files or deployment secret stores.
+- Preferred model: secrets such as `KB_API_KEY` and `GITHUB_TOKEN` live in deployment secret stores or process environment variables.
+- Supported local/dev model: `/admin` can write `KB_API_KEY` and `GITHUB_TOKEN` into local `.env`.
+- Admin responses must not echo stored secret values back to the browser after save.
 - Docs should only reference secret names, not values.
 - Generated docs must redact secrets by default.
 
@@ -33,12 +36,16 @@ review_cycle_days: 21
 - Path traversal and absolute-path writes are denied.
 - Only approved file types are writable.
 - Writes from `source=api` remain review-gated through PR workflow.
+- Admin config writes change local instance configuration only; they do not authorize content writes outside existing approval boundaries.
+- Admin start/restart actions only launch derived tmux commands for the configured local checkout and sessions; they do not elevate privileges or infer a broader process manager.
 
 ## Security Review Triggers
 
 Update this document when changing:
 
 - auth middleware/dependency behavior
+- admin route exposure or operator trust boundary
 - request validation and path sanitization
+- secret storage or secret presentation behavior in admin/config flows
 - external webhook/publish execution semantics
 - GitHub token scope or PR automation behavior
diff --git a/docs/exec-plans/active/admin-ui-bootstrap.md b/docs/exec-plans/active/admin-ui-bootstrap.md
@@ -0,0 +1,55 @@
+---
+owner: platform
+status: draft
+last_verified: 2026-03-12
+source_of_truth:
+  - ../../../kb-server/AGENTS.md
+  - ../../../kb-server/app/main.py
+  - ../../../kb-server/app/core/config.py
+related_code:
+  - ../../../kb-server/app/api/routes
+  - ../../../kb-server/app/services
+related_tests:
+  - ../../../kb-server/tests
+review_cycle_days: 14
+---
+
+# Admin UI Bootstrap
+
+## Objective
+
+Add an initial admin surface to `kb-server` for setup, configuration, and operational visibility without changing the core note-writing workflow.
+
+## First Slice
+
+Ship a minimal but real `/admin` experience that provides:
+
+- current configuration visibility for key settings
+- write support for local `.env` configuration updates
+- write-only secret update inputs for `KB_API_KEY` and `GITHUB_TOKEN`
+- readiness and vault/git status summary
+- recent jobs, vault events, and publish runs
+- visibility into pending `kb-api/*` PR state when GitHub is configured
+
+## Non-Goals
+
+- no note editing UI
+- no browser-triggered host provisioning
+- no direct mutation of PR approval semantics
+- no requirement to store secrets in `.env`
+
+## Design Constraints
+
+- The admin UI is an operator surface layered on top of existing API and worker behavior.
+- Existing API-key middleware remains in force when `KB_API_KEY` is configured.
+- Secret values are never returned in API responses after save.
+- Config writes update `.env`, but operators should be told that process restart may be required for full effect.
+- The UI should degrade cleanly when GitHub is unconfigured or the vault/db is unavailable.
+
+## Delivery Plan
+
+1. Add admin service helpers for status aggregation and `.env` persistence.
+2. Add `/admin`, `/admin/api/state`, and `/admin/api/config`.
+3. Render a lightweight in-app dashboard with setup and status sections.
+4. Add focused tests for config persistence and admin endpoints.
+5. Update README with usage and restart expectations.
diff --git a/docs/generated/api-surface.md b/docs/generated/api-surface.md
@@ -1,11 +1,12 @@
 ---
 owner: platform
 status: generated
-last_verified: 2026-03-07
+last_verified: 2026-03-12
 source_of_truth:
   - ../../kb-server/app/api/routes/health.py
   - ../../kb-server/app/api/routes/notes.py
   - ../../kb-server/app/api/routes/publish.py
+  - ../../kb-server/app/api/routes/admin.py
 related_code:
   - ../../scripts/generate_context_artifacts.py
 related_tests:
@@ -15,7 +16,7 @@ review_cycle_days: 7
 
 # API Surface (Generated)
 
-Generated on `2026-03-07` from route handlers.
+Generated on `2026-03-12` from route handlers.
 
 | Method | Path |
 | --- | --- |
@@ -26,5 +27,12 @@ Generated on `2026-03-07` from route handlers.
 | `PUT` | `/{path:path}` |
 | `DELETE` | `/{path:path}` |
 | `POST` | `/publish` |
+| `GET` | `/admin` |
+| `GET` | `/admin/api/state` |
+| `POST` | `/admin/api/config` |
+| `POST` | `/admin/api/start` |
+| `POST` | `/admin/api/restart` |
+| `POST` | `/admin/api/start-worker` |
+| `POST` | `/admin/api/restart-worker` |
 
 Do not edit manually. Regenerate with `python3 scripts/generate_context_artifacts.py`.
diff --git a/docs/generated/env-catalog.md b/docs/generated/env-catalog.md
@@ -1,7 +1,7 @@
 ---
 owner: platform
 status: generated
-last_verified: 2026-03-07
+last_verified: 2026-03-12
 source_of_truth:
   - ../../kb-server/.env.example
   - ../../kb-server/app/core/config.py
@@ -16,7 +16,7 @@ review_cycle_days: 7
 
 # Environment Catalog (Generated)
 
-Generated on `2026-03-07` from settings and env sources.
+Generated on `2026-03-12` from settings and env sources.
 
 ## kb-server `.env.example`
 
@@ -36,6 +36,9 @@ Generated on `2026-03-07` from settings and env sources.
 | `GITHUB_REPO` | `owner/repo` |
 | `QUARTZ_BUILD_COMMAND` | `` |
 | `QUARTZ_WEBHOOK_URL` | `` |
+| `ADMIN_TMUX_SESSION` | `kb-api` |
+| `ADMIN_TMUX_WORKER_SESSION` | `kb-worker` |
+| `ADMIN_TMUX_WORKDIR` | `/absolute/path/to/flight-deck/kb-server` |
 | `API_HOST` | `0.0.0.0` |
 | `API_PORT` | `8000` |
 
@@ -57,6 +60,9 @@ Generated on `2026-03-07` from settings and env sources.
 | `git_pull_interval_seconds` | `60` |
 | `quartz_build_command` | `""` |
 | `quartz_webhook_url` | `""` |
+| `admin_tmux_session` | `"kb-api"` |
+| `admin_tmux_worker_session` | `"kb-worker"` |
+| `admin_tmux_workdir` | `Path("/srv/flightdeck/kb-server")` |
 | `api_host` | `"0.0.0.0"` |
 | `api_port` | `8000` |
 

diff --git a/docs/generated/stale-docs-report.md b/docs/generated/stale-docs-report.md
@@ -1,7 +1,7 @@
 ---
 owner: platform
 status: generated
-last_verified: 2026-03-07
+last_verified: 2026-03-12
 source_of_truth:
   - ../../scripts/docs_garden.py
 related_code:
@@ -14,7 +14,7 @@ review_cycle_days: 7
 
 # Stale Documentation Report
 
-Generated: `2026-03-07`
+Generated: `2026-03-12`
 
 ## Ownership Summary
 

diff --git a/docs/product-specs/kb-server.md b/docs/product-specs/kb-server.md
@@ -4,13 +4,16 @@ status: verified
 last_verified: 2026-03-07
 source_of_truth:
   - ../../kb-server/app/api/routes/notes.py
+  - ../../kb-server/app/api/routes/admin.py
   - ../../kb-server/app/services/current_view_service.py
   - ../../kb-server/app/core/config.py
 related_code:
   - ../../kb-server/app/services/git_batcher.py
+  - ../../kb-server/app/services/admin_service.py
   - ../../kb-server/app/workers/autosave.py
 related_tests:
   - ../../kb-server/tests/test_current_view.py
+  - ../../kb-server/tests/test_admin.py
   - ../../kb-server/tests/test_source_and_delete.py
 review_cycle_days: 14
 ---
@@ -30,23 +33,35 @@ Provide a file-first API over a Git-backed vault with explicit approval boundari
   - `source=api` for PR-based pending writes
   - `source=human` for direct approved writes
 - Writes to `view=current` are rejected.
+- `GET /admin` exposes an operator-facing setup and status surface.
+- `GET /admin/api/state` returns admin config/status state for the local instance.
+- `POST /admin/api/config` writes local configuration updates to `kb-server/.env`.
+- `POST /admin/api/start` launches the derived tmux start command for the API.
+- `POST /admin/api/restart` launches the derived tmux restart command for the API.
+- `POST /admin/api/start-worker` launches the derived tmux start command for the autosave worker.
+- `POST /admin/api/restart-worker` launches the derived tmux restart command for the autosave worker.
+- `app/streamlit_admin.py` provides an operator dashboard backed by the admin API.
 
 ## Approval Model
 
 - API-origin changes are batched to daily `kb-api/*` branches and PRs.
 - Human-origin changes go to base branch directly.
 - Mainline approval remains controlled by maintainers.
+- The admin UI is not a note-editing surface and does not bypass PR-based approval for content changes.
 
 ## Guardrails
 
 - Allowed file extensions: `.md`, `.markdown`, `.txt`.
 - No absolute paths and no traversal outside vault root.
-- API key auth enforced when configured.
+- API key auth is enforced on non-admin API routes when configured.
+- Admin routes are intentionally available without `X-API-Key` so the local dashboard can bootstrap and operate the instance.
+- Admin config writes are local instance management actions only; operators must still provision the DB, vault repo, and host runtime outside the browser.
+- Admin runtime control derives the API and worker tmux commands from `ADMIN_TMUX_SESSION`, `ADMIN_TMUX_WORKER_SESSION`, `ADMIN_TMUX_WORKDIR`, `API_HOST`, and `API_PORT`.
+- Process environment variables override `.env`, including when `.env` is edited through `/admin`.
 
 ## Related Operational Docs
 
 - `../../kb-server/README.md`
 - `../../kb-server/BRANCHING_AND_CURRENT_VIEW.md`
 - `../SECURITY.md`
 - `../RELIABILITY.md`
-
diff --git a/kb-server/.env.example b/kb-server/.env.example
@@ -5,6 +5,7 @@ VAULT_PATH=/Users/yashturkar/Downloads/flightdeck/vault
 DATABASE_URL=postgresql://kb:kb@localhost:5432/kb
 
 # API key — every request must include X-API-Key header when set.
+# Recommended: leave blank here and export KB_API_KEY in your shell or service env.
 # Leave blank to disable auth (development only).
 KB_API_KEY=
 
@@ -22,6 +23,7 @@ GIT_BATCH_DEBOUNCE_SECONDS=10
 GIT_BATCH_BRANCH_PREFIX=kb-api
 
 # GitHub API for PR creation (required for API write workflow)
+# Recommended: leave blank here and export GITHUB_TOKEN in your shell or service env.
 # Create a token at https://github.com/settings/tokens with 'repo' scope
 GITHUB_TOKEN=
 GITHUB_REPO=owner/repo
@@ -30,6 +32,12 @@ GITHUB_REPO=owner/repo
 QUARTZ_BUILD_COMMAND=
 QUARTZ_WEBHOOK_URL=
 
+# Streamlit dashboard tmux control
+# The dashboard derives API/worker start/restart commands from these values.
+ADMIN_TMUX_SESSION=kb-api
+ADMIN_TMUX_WORKER_SESSION=kb-worker
+ADMIN_TMUX_WORKDIR=/absolute/path/to/flight-deck/kb-server
+
 # API
 API_HOST=0.0.0.0
 API_PORT=8000