diff --git a/configuration/overview.mdx b/configuration/overview.mdx index 7cd1adf..4d2801b 100644 --- a/configuration/overview.mdx +++ b/configuration/overview.mdx @@ -39,12 +39,14 @@ Supported workload classes are `unknown`, `cpu_only`, `gpu_required`, `inference ## Optional integrations - Pushover queue alerts: `pushover_alerts_enabled`, `pushover_app_token`, `pushover_user_key`, `pushover_api_url`, `queue_alert_*`. +- Hermes alert webhook (optional): `hermes_alert_webhook_enabled`, `hermes_alert_webhook_url`, `hermes_alert_webhook_secret`, `hermes_alert_webhook_timeout_sec`. - Queue pump (timer-driven dispatch): `queue_pump_enabled`, `queue_pump_followup_launch_enabled`, `queue_pump_paper_draft_enabled`. - Multi-worker routing: `worker_targets`, `workload_machine_targets` (maps workload classes such as `cpu_only` and `gpu_required` to named worker targets). - Store backend: `control_plane_store_backend` (`sqlite`, `supabase_readonly`, or `supabase`), `enoch_core_store_backend`, `supabase_database_url`. Production on `enoch-core` uses `supabase` with local Postgres; the setting name is a compatibility adapter label. - Paper writer: `paper_writer_provider`, `paper_writer_base_url`, `paper_writer_model`, `paper_writer_api_key`, `paper_writer_*` tuning, and fallback. - Evidence sync: `paper_evidence_sync_enabled`, `paper_evidence_sync_ssh_host`, `paper_evidence_sync_remote_root`, `paper_evidence_sync_timeout_sec`. - Route observability (private diagnostics): `route_observability_enabled`, `route_observability_log_path`, `route_observability_slow_ms`, `route_observability_memory_warn_rss_mib`. +- Operational trace (private diagnostics): `operational_trace_enabled`, `operational_trace_log_path`, `operational_trace_max_payload_bytes` (minimum 1024). Keep disabled unless you intentionally want raw request/response payloads captured. ## Deprecated aliases @@ -193,6 +195,9 @@ The following JSON mirrors the repository `config.example.json` baseline at the "route_observability_log_path": "", "route_observability_slow_ms": 1000, "route_observability_memory_warn_rss_mib": 0, + "operational_trace_enabled": false, + "operational_trace_log_path": "", + "operational_trace_max_payload_bytes": 16384, "control_plane_store_backend": "sqlite", "enoch_core_store_backend": "control_plane", "supabase_database_url": "", diff --git a/current-runtime-snapshot.mdx b/current-runtime-snapshot.mdx index 5c94eae..647e6c1 100644 --- a/current-runtime-snapshot.mdx +++ b/current-runtime-snapshot.mdx @@ -8,20 +8,36 @@ description: "Canonical short reference for Enoch's current runtime hosts, stora This page is the canonical short reference for current Enoch runtime facts. If longer runbooks or guides drift, update this page first and link back here. + +The canonical snapshot in the system repository at [`docs/current-runtime-snapshot.md`](https://github.com/alias8818/enoch-agentic-research-system/blob/main/docs/current-runtime-snapshot.md) is the source of truth for runtime hosts, paths, and dashboard cutover state. This page mirrors the public-safe facts and intentionally omits private deploy hostnames, LAN IPs, and live credentials. If the two pages disagree, the system-repo page wins. + + ## Runtime hosts | Host | Role | Path | Notes | | --- | --- | --- | --- | -| `enoch-core` | Control plane | `/opt/enoch-control-plane` | Runs the FastAPI control plane, dashboard/API, local Postgres runtime storage, automation timers, and paper/corpus tooling. | +| `enoch-core` (reference control VM) | Control plane | `/opt/enoch-control-plane` | Runs the FastAPI control plane, dashboard/API, local Postgres runtime storage, automation timers, and paper/corpus tooling. Public docs intentionally omit private deploy aliases. | | GB10 | Worker gate | `~/projects/enoch_testing_ground/enoch-control-plane` | Runs native Codex worker execution, process/telemetry tracking, project workspaces, evidence, and worker callbacks. | +## Operator dashboard + +| Path | Role | +| --- | --- | +| `/control/dashboard-v2` | **Canonical** operator console (React/TypeScript Dashboard V2). Use this URL for day-to-day operations. | +| `/control/dashboard` | Legacy URL; **307 redirect** to `/control/dashboard-v2` (hash preserved) after the 2026-05-21 cutover. | +| `/dashboard` | Legacy worker-gate shell; redirects to `/control/dashboard-v2` on current deployments. | + +For local development, the canonical V2 URL is `http://127.0.0.1:8787/control/dashboard-v2`. + ## Storage/source of truth Local Postgres/control-plane storage on `enoch-core` is the current runtime source of truth for ideas, projects, queue items, runs, papers, events, and the corpus import ledger. Notion is a legacy provenance/intake compatibility path. Supabase Cloud is not current runtime intake or storage; `supabase_*` names in -code and scripts are compatibility or migration-adapter naming. +code and scripts are compatibility or migration-adapter naming. If a UI label +or dashboard footer still mentions "Supabase", treat it as a compatibility +label for the local Postgres adapter, not Supabase Cloud. ## Worker execution path diff --git a/deployment.mdx b/deployment.mdx index 4fc39ff..c966e08 100644 --- a/deployment.mdx +++ b/deployment.mdx @@ -76,13 +76,13 @@ sudo systemctl status enoch-control-plane.service curl -fsS http://127.0.0.1:8787/healthz ``` -Open the dashboard and authenticate with the configured inbound token: +Open the **canonical** operator console and authenticate with the configured inbound token: ```text -http://:8787/control/dashboard +http://:8787/control/dashboard-v2 ``` -`/dashboard` redirects to the same shell. The dashboard uses bounded `/control/api/v1/*` read models by default, so the first screen stays focused on operator questions rather than raw JSON. +`/control/dashboard` 307-redirects to `/control/dashboard-v2`. The shorter `/dashboard` legacy worker-gate shell also redirects to V2. The dashboard uses bounded `/control/api/v1/*` read models by default, so the first screen stays focused on operator questions rather than raw JSON. ## Configure the worker diff --git a/docs-audit-notes.md b/docs-audit-notes.md index 26b9958..7538cbf 100644 --- a/docs-audit-notes.md +++ b/docs-audit-notes.md @@ -1,4 +1,31 @@ -# Docs audit notes — 2026-05-21 +# Docs audit notes + +This file summarizes the docs audit history against the three source repositories and what remains uncertain. + +## 2026-06-20 refresh — findings still open + +This audit was re-run against the live source repos on 2026-06-20. Key drift from the prior (2026-05-21) audit: + +1. **Runtime version drift**: System repo `VERSION` and `pyproject.toml` report `1.41.25` (released 2026-06-20). The docs `release-notes.mdx` listed milestones only through `0.3.0`. Docs now point readers to the canonical `CHANGELOG.md` and surface the current version via an `` block. The detailed milestone entries for `0.1.0`, `0.2.0`, and `0.3.0` are retained for the terminology changes they introduced (ENOCH_CONFIG, control_api_bearer_token, project_decision.json contract) but new entries from `1.0.0` through `1.41.25` are not mirrored here — they are best read in the canonical `CHANGELOG.md`. + +2. **Dashboard cutover**: The source repo's `docs/current-runtime-snapshot.md` (merged 2026-05-21) and `docs/dashboard-v2-deploy.md` establish `/control/dashboard` as a 307 redirect to `/control/dashboard-v2`. Older docs said `/dashboard` redirected to `/control/dashboard` (the legacy URL). All `quickstart`, `deployment`, and `current-runtime-snapshot` references now point to `/control/dashboard-v2` as the canonical URL. + +3. **Corpus count drift**: `introduction.mdx` previously said `388/388` for packaging/provenance; `quality/packaging_provenance_report.json` and `quality/claim_evidence_audit.json` both report `389/389`. Updated. `guides/paper-artifacts.mdx` already said `389/389` and was kept. A `` was added to flag that both numbers must be re-verified from the canonical JSON before quoting externally. + +4. **Configuration field drift**: Source `config.example.json` and `enoch_control_plane/config.py` include `operational_trace_*` and `hermes_alert_webhook_*` field groups. The docs `configuration/overview.mdx` did not list them. Both groups were added. + +5. **Screenshot redaction — public-repo safety**: All five PNGs in `images/` (`dashboard-status-blocked.png`, `dashboard-active-queue.png`, `dashboard-queued-queue.png`, `dashboard-paper-reviews.png`, `dashboard-papers.png`) currently expose: + - A UI footer reading "Bounded Supabase read models · raw states stay in drill-down views" that conflicts with the public docs framing that Supabase Cloud is compatibility-only. + - Internal paper IDs and counts that drift over time (e.g. `acceptance-length-cuda-graph-bank`, 496/498 corpus counts). + - Pre-cutover dashboard URLs (visible in `Open localhost:51111.pdf` style links). + + Each guide page that uses a screenshot now has an explicit `` placeholder noting the image is pending replacement with a redacted, public-safe capture. The replacement PNGs need to be re-captured from a public-safe dashboard view (after the V2 cutover and after the dashboard footer is updated to drop the "Supabase" label). Until then, treat the existing PNGs as layout references only. + +6. **Source repo quickstart token length**: The source repo `docs/quickstart.md` uses `secrets.token_urlsafe(32)` while the docs `quickstart.mdx` and source `docs/deployment-guide.md` use `48`. Both are operationally valid. Added a `` explaining the difference; no change to the example value. + +7. **Private deploy alias**: The source repo references a private deploy host alias. This is not a public fact. The docs `current-runtime-snapshot.mdx` describes `enoch-core` only as the reference control VM and intentionally omits the private alias. + +## 2026-05-21 audit — historical This file summarizes what was reconciled during the enoch-docs audit against the three source repositories and what remains uncertain. @@ -32,7 +59,7 @@ This file summarizes what was reconciled during the enoch-docs audit against the - `TODO` / `FIXME`: None found in any .mdx file. - `coming soon`: None found. - Private LAN IPs (192.168.x, 10.x, 172.16-31.x): None found in docs text (only in SVG path data in logo files). -- Internal hostnames (`enoch-core.exe.xyz`): Not present in any docs file. +- Internal hostnames/private deploy aliases: Not present in any docs file. - Placeholder screenshots: All 5 images reference real PNG files in `images/`. ### Link validation diff --git a/guides/dispatch-flow.mdx b/guides/dispatch-flow.mdx index e714504..164f6c4 100644 --- a/guides/dispatch-flow.mdx +++ b/guides/dispatch-flow.mdx @@ -17,6 +17,10 @@ curl -fsS -H "Authorization: Bearer $ENOCH_CONTROL_TOKEN" \ Review `dispatch_safe` and `dispatch_blockers` before proceeding. The operator dashboard UI is at `http://:8787/control/dashboard`. The shorter `/dashboard` URL redirects to the same shell on current deployments. + +The dashboard screenshot in this section is pending replacement with a public-safe, redacted capture. The current `images/dashboard-status-blocked.png` includes an internal UI footer ("Bounded Supabase read models") that conflicts with the public-facing compatibility-only framing in [current runtime snapshot](/current-runtime-snapshot), and may include internal paper IDs. Treat the existing PNG as illustrative of layout only, not as a verified public-safe reference. + + ![Current operator overview showing attention, running work, paper-writing, and publish/import cards](/images/dashboard-status-blocked.png) Use the dashboard as a fast visual check, but trust the API response as the source of truth for automation. @@ -63,6 +67,10 @@ curl -fsS -H "Authorization: Bearer $ENOCH_CONTROL_TOKEN" \ The queue tabs show the same read model from different operator angles. Empty active and queued views are useful during smoke testing because they prove the dashboard can read canonical queue state without launching work. + +The two queue-tab screenshots below are pending replacement. Both contain the same compatibility-only "Supabase" footer string and reference counts that may drift over time. Until redacted replacements land, use them as layout references only. + + ![Current active queue tab showing bounded active-work rows](/images/dashboard-active-queue.png) ![Current queued queue tab showing bounded ready-queue rows](/images/dashboard-queued-queue.png) diff --git a/guides/paper-artifacts.mdx b/guides/paper-artifacts.mdx index de4fa4f..1a83053 100644 --- a/guides/paper-artifacts.mdx +++ b/guides/paper-artifacts.mdx @@ -68,6 +68,10 @@ If `paper_writer_fallback_enabled` is `true`, the writer falls back to a determi After the artifact is written, a publication automation record may still expose legacy fields such as `review_status` with values like `unreviewed` or `triage_ready`. Treat those as raw compatibility/detail fields, not the operator work queue. The packaging/provenance check includes a ranked checklist of items the automation lane must pass, fail, or accept as a recorded risk before the paper can be finalized. It does not validate peer review, scientific correctness, or independent replication. + +The publication automation screenshot below is pending replacement. The current `images/dashboard-paper-reviews.png` shows internal paper IDs, score details, and a compatibility-only "Supabase" footer string. Until redacted, treat as layout-only. + + ![Current publication automation queue showing automation states, paper states, rank score, and checklist progress](/images/dashboard-paper-reviews.png) @@ -86,6 +90,10 @@ Use dry-run first. In current deployments this path should remain explicit and b Paper automation APIs support claiming automation items, updating checklist items, changing raw automation state, rewriting drafts, marking papers ready for finalization, and preparing finalization packages. The dashboard presents the simpler operator lanes: write, finalize, publish/import, published/imported, and done/no paper. Generated prose remains AI-generated and not peer-reviewed. + +The papers queue screenshot below is pending replacement. It currently exposes paper paths and counts that drift over time, and a compatibility-only "Supabase" footer string. Until redacted, treat as layout-only. + + ![Current papers queue showing generated draft paths, claim ledger paths, and manifest paths](/images/dashboard-papers.png) diff --git a/index.mdx b/index.mdx index 6f4e0a5..e5f2629 100644 --- a/index.mdx +++ b/index.mdx @@ -41,7 +41,7 @@ The hosted docs website is [https://solo-09d10f60.mintlify.app/](https://solo-09 Learn what Enoch does, what it does not claim, and how the control plane fits with the corpus. - Clone the code repo, create a local config, start the FastAPI app, and verify the dashboard/API path. + Clone the code repo, create a local config, start the FastAPI app, and verify the Dashboard V2 + bounded v1 API path. Follow the two-machine reference deployment for a control VM and worker-gate node. diff --git a/introduction.mdx b/introduction.mdx index bd62ccf..1f222c9 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -51,7 +51,11 @@ and compatibility boundaries, see ## What Enoch is not -Enoch is not a peer-review system, a guarantee of scientific novelty, a replacement for expert review, or a collection of old workflow-tool exports. The corpus is useful because it preserves generated work and evidence boundaries, not because every generated claim is true. The current public status separates 388/388 packaging/provenance lint from 389/389 strict claim/evidence audit pass. For the full review boundary, read [quality floor and signal visibility](/concepts/quality-floor). +Enoch is not a peer-review system, a guarantee of scientific novelty, a replacement for expert review, or a collection of old workflow-tool exports. The corpus is useful because it preserves generated work and evidence boundaries, not because every generated claim is true. The current public status separates 389/389 packaging/provenance lint from 389/389 strict claim/evidence audit pass. For the full review boundary, read [quality floor and signal visibility](/concepts/quality-floor). + + +The packaging/provenance and strict audit counts above are the values reported by `enoch-ai-research-corpus` `quality/packaging_provenance_report.json` and `quality/claim_evidence_audit.json` at the time this page was last audited. Re-run the corpus release validators or check the canonical JSON before quoting them externally; counts can change as the corpus is re-imported. + ## Recommended next step diff --git a/quickstart.mdx b/quickstart.mdx index c63f684..8dcec47 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -29,6 +29,10 @@ data['project_root'] = str(pathlib.Path('.local/projects').resolve()) data['dispatch_script_path'] = str(pathlib.Path('deploy/enoch_codex_dispatch.sh').resolve()) data['control_api_bearer_token'] = secrets.token_urlsafe(48) data['completion_callback_token'] = secrets.token_urlsafe(48) + + +The source repository quickstart uses `secrets.token_urlsafe(32)` for both tokens; either length is acceptable because the token is opaque to the runtime. The deployment guide uses 48 bytes for stronger entropy on long-lived deployments. Do not commit any token value. + data['completion_callback_url'] = 'http://127.0.0.1:8787/omx/event' data['worker_wake_gate_url'] = 'http://127.0.0.1:8787' data['worker_wake_gate_bearer_token'] = data['control_api_bearer_token'] @@ -46,9 +50,13 @@ export ENOCH_CONFIG=$PWD/.local/config/config.json uv run uvicorn enoch_control_plane.app:app --host 127.0.0.1 --port 8787 ``` -Open `http://127.0.0.1:8787/control/dashboard`. +Open the **canonical** operator console: + +```text +http://127.0.0.1:8787/control/dashboard-v2 +``` -If you use the shorter `/dashboard` URL, it redirects to the same operator shell. +If you use the shorter `/dashboard` URL, it redirects to `/control/dashboard-v2` (the canonical V2 shell) on current deployments. `/control/dashboard` also 307-redirects to `/control/dashboard-v2`. The dashboard opens as a professional operator console. It leads with attention, running work, paper-writing, finalization, and publish/import cards instead of raw JSON. diff --git a/reference/api-endpoints.mdx b/reference/api-endpoints.mdx index a5f2415..2f3aa2d 100644 --- a/reference/api-endpoints.mdx +++ b/reference/api-endpoints.mdx @@ -3,7 +3,7 @@ title: "API endpoints" description: "A source-derived map of the main Enoch API surfaces." --- -Enoch serves control-plane and worker APIs from FastAPI apps that commonly listen on port `8787`. All endpoints except root `GET /healthz`, `GET /dashboard`, and `GET /control/dashboard` require a bearer token. The control-plane health endpoint is `GET /control/health` and does require authentication. The dashboard shell is unauthenticated for the initial page load; it prompts for a bearer token and stores it in `localStorage` for subsequent API calls. Read the Authentication section below before making your first request. +Enoch serves control-plane and worker APIs from FastAPI apps that commonly listen on port `8787`. All endpoints except root `GET /healthz`, `GET /dashboard`, `GET /control/dashboard`, and `GET /control/dashboard-v2` require a bearer token. The control-plane health endpoint is `GET /control/health` and does require authentication. The dashboard shell is unauthenticated for the initial page load; it prompts for a bearer token and stores it in `localStorage` for subsequent API calls. Read the Authentication section below before making your first request. This page maps the main endpoint groups present in the local source snapshot. It is not a generated OpenAPI reference; verify request and response models against the code before building clients. The operator dashboard now prefers bounded `/control/api/v1/*` read models, while older broad status surfaces remain available for compatibility and debug. For current runtime topology and compatibility boundaries, see diff --git a/reference/authorship-provenance.mdx b/reference/authorship-provenance.mdx index d9d06fb..986e080 100644 --- a/reference/authorship-provenance.mdx +++ b/reference/authorship-provenance.mdx @@ -19,6 +19,10 @@ Use this framing when describing the corpus: The dashboard should make provenance visible before a generated artifact is treated as ready. In the current capture below, every paper row keeps links to the draft, claim ledger, and manifest instead of presenting the draft as a standalone publication. + +The dashboard screenshot below is pending replacement with a redacted, public-safe capture. The current `images/dashboard-papers.png` shows paper paths and counts that drift, and includes the compatibility-only "Supabase" footer string. Until replaced, treat as a layout reference only. + + ![Current papers queue showing generated draft, claim ledger, and manifest paths](/images/dashboard-papers.png) diff --git a/release-notes.mdx b/release-notes.mdx index f34311c..30fe893 100644 --- a/release-notes.mdx +++ b/release-notes.mdx @@ -5,10 +5,14 @@ description: "Version history and compatibility notes for Enoch Control Plane." # Release notes -The canonical runtime changelog lives in the system repository at [`CHANGELOG.md`](https://github.com/alias8818/enoch-agentic-research-system/blob/main/CHANGELOG.md). This page mirrors the operationally important notes for docs readers. +The canonical runtime changelog lives in the system repository at [`CHANGELOG.md`](https://github.com/alias8818/enoch-agentic-research-system/blob/main/CHANGELOG.md). It tracks every published version. This page mirrors only the milestones that introduced public-facing capability or terminology changes for docs readers. For the current runtime topology and compatibility boundary, see [current runtime snapshot](/current-runtime-snapshot). + +The current runtime version is **1.41.25** (released 2026-06-20). Always read [`VERSION`](https://github.com/alias8818/enoch-agentic-research-system/blob/main/VERSION) in the system repository for the absolute current version. The full version history is in [`CHANGELOG.md`](https://github.com/alias8818/enoch-agentic-research-system/blob/main/CHANGELOG.md). + + ## 0.3.0 — 2026-05-15 - Added durable worker callback outbox and replay support for transient callback failures.