Merge pull request #2044 from Open-Source-Legal/docs/authority-console

Add Authority Console architecture doc (#2037 follow-up)

Author: JSv4

changelog.d/authority-console-doc.added.md

@@ -0,0 +1,16 @@
+- **Authority Console architecture doc.** Added
+  `docs/architecture/authority-console.md` — an as-built reference for the unified
+  Authority Console (PR #2037, issue #1997 management layer): the `/admin/authority`
+  tabs and routes, the `AuthorityNamespace`-as-spine model (string-join `detail()`,
+  the `source` baseline/manual ownership marker + loader skip, `created_by`),
+  `AuthorityNamespaceService` / `AuthoritySourceProviderService` / the
+  `AuthorityFrontierService` action verbs over the single `mark()` primitive, the
+  one `is_authority_admin` gate, the GraphQL surface, migrations 0099/0100, and a
+  Design notes section preserving the chosen architecture and five settled design
+  decisions. Wired into the mkdocs `Architecture` nav after Reference-Web Enrichment.
+- **Refreshed sibling docs.** Updated `docs/architecture/reference-web-enrichment.md`
+  and `docs/guides/ingesting-authorities.md` to name the merged-in tabs (the
+  standalone "enrichment runner" → **Runs tab**; the "authority-sources monitor" →
+  **Queue tab**) and point at the committed
+  `authorities--console-queue--with-data.png` screenshot, replacing references to the
+  deleted standalone panels.

docs/architecture/authority-console.md

@@ -164,7 +164,7 @@ authority's own outbound citations at `depth+1`.
 
 Each frontier row carries a `discovery_state`:
 
-`queued` · `in_progress` · `discovered` · `ingested` · `resolved` · `failed` ·
+`queued` · `in_progress` · `ingested` · `failed` ·
 `unsupported` · `blocked_license` · `unlocated` · `pending_approval` · `deferred_cap`
 
 Two pieces worth calling out:
@@ -184,35 +184,39 @@ Two pieces worth calling out:
 ## Operating it
 
 > **Step-by-step how-to:** for runnable procedures — ingesting a supported
-> source (shell, crawl, or the runner UI) and adding a new provider to flip an
+> source (shell, crawl, or the Runs tab) and adding a new provider to flip an
 > authority from `unsupported` to supported — see
 > [Ingesting Authorities & Adding Providers](../guides/ingesting-authorities.md).
+> The admin surfaces named below are tabs of the
+> [Authority Console](authority-console.md) at `/admin/authority`.
 
-### Trigger — the enrichment runner
+### Trigger — the Runs tab
 
-`/admin/authority/runs` (and a per-corpus card) drives runs via the
+`/admin/authority/runs` (the Runs tab of the Authority Console, and a per-corpus
+card) drives runs via the
 `runCorpusEnrichment` mutation. Pick reference enrichment and/or authority crawl,
 optionally enable the LLM detection tier and the advanced crawl bounds (max depth,
 min demand, max authorities, per-jurisdiction cap, token budget), and Run. The
 mutation is gated on corpus **UPDATE** (see Permissions below).
 
 ![Enrichment runner with a live job list](../assets/images/screenshots/auto/enrichment--runner-and-jobs--with-data.png)
 
-### Monitor — live job status & the authority-sources monitor
+### Monitor — live job status & the Queue tab
 
-The runner's job list shows each `Analysis` live (`RUNNING` / `COMPLETED` /
+The Runs tab's job list shows each `Analysis` live (`RUNNING` / `COMPLETED` /
 `FAILED`, elapsed, result summary) via an `Analysis → Notification` signal over the
 notification WebSocket.
 
-For the instance-wide picture, the read-only **authority-sources monitor** at
-`/admin/authority/queue` (superuser-only) is the ingestion backlog over the whole
+For the instance-wide picture, the **Queue tab** of the Authority Console
+at `/admin/authority/queue` (superuser-only) is the ingestion backlog over the whole
 `AuthorityFrontier`: per-state count chips, jurisdiction / type / provider filters,
 search, and a backlog-first table. It is powered by the `authorityFrontier` relay
 connection + `authorityFrontierStats` (both superuser-gated) and
-`AuthorityFrontierService.admin_state_counts`. It is observational — triggering
-stays in the runner.
+`AuthorityFrontierService.admin_state_counts`. Beyond observing, it exposes per-row
+**requeue / reset / reroute / approve / delete** verbs; triggering enrichment runs
+stays on the Runs tab.
 
-![Global authority-sources monitor](../assets/images/screenshots/auto/authorities--sources-monitor--with-data.png)
+![Authority Console — Queue tab](../assets/images/screenshots/auto/authorities--console-queue--with-data.png)
 
 ### Explore — the governance graph
 
@@ -241,7 +245,7 @@ exception: they may trigger enrichment/crawl on any corpus they can **READ**
 without holding `UPDATE` — a retained admin privilege documented in
 `docs/permissioning/consolidated_permissioning_guide.md`. The exemption widens the
 *write-trigger* only; a superuser still cannot see a corpus they lack READ on (no
-blanket bypass). The `/admin/authority/queue` monitor and the `authorityFrontier`
+blanket bypass). The `/admin/authority/queue` Queue tab and the `authorityFrontier`
 queries are superuser-gated at the node level.
 
 ---
@@ -263,8 +267,8 @@ queries are superuser-gated at the node level.
   the new section version — see `docs/architecture/reference-web-versioning.md`.
 - **Live per-document progress counter (deferred).** Progress during a run is
   conveyed today by the RUNNING job status, the incrementally-appearing refs, and
-  the "In progress" badge. A live per-document counter on the enrichment runner
-  (e.g. "12 / 75 documents · 31 references") would need a transient
+  the "In progress" badge. A live per-document counter on the Authority Console
+  Runs tab (e.g. "12 / 75 documents · 31 references") would need a transient
   `ENRICHMENT_PROGRESS` WebSocket message emitted from both `apply` paths and a
   new handler in `useNotificationWebSocket` → `useEnrichmentJobs` →
   `EnrichmentJobList`. Deferred as its own change (the WS path is not

docs/architecture/reference-web-enrichment.md

@@ -135,9 +135,10 @@ print(summary)
 task — a worker must be running, and it won't be reflected the instant the crawl
 reports `ingested`.
 
-### Option C — the enrichment runner (no shell)
+### Option C — the Runs tab (no shell)
 
-`/admin/authority/runs` (and the per-corpus enrichment card) drives the same path via
+`/admin/authority/runs` (the Authority Console Runs tab, and the per-corpus
+enrichment card) drives the same path via
 the `runCorpusEnrichment` mutation. It requires corpus **UPDATE** (superusers
 are exempt from UPDATE but still need READ).
 
@@ -173,18 +174,16 @@ finalized references to seed from.
 
 ### Spotting what needs a provider
 
-The read-only authority-sources monitor at `/admin/authority/queue`
+The read-only Queue tab of the Authority Console at `/admin/authority/queue`
 (superuser-only) is the instance-wide ingestion backlog over the whole
 `AuthorityFrontier`.
 
-![Global authority-sources monitor](../assets/images/screenshots/auto/authorities--sources-monitor--with-data.png)
+![Authority Console — Queue tab](../assets/images/screenshots/auto/authorities--console-queue--with-data.png)
 
 Click the **Unsupported** state chip to filter to the cited authorities no
 provider can handle. These — bodies of law with demand but no `.gov` source the
 system knows how to fetch — are exactly the candidates for a new provider (or a
-no-code alternative below):
-
-![Authority-sources monitor filtered to the unsupported state](../assets/images/screenshots/auto/authorities--sources-monitor--unsupported.png)
+no-code alternative below).
 
 ### The provider contract
 
@@ -329,5 +328,6 @@ the `Unsupported` chip count on `/admin/authority/queue` should drop.
 - The gate enforces **`public-domain` license + an allowlisted `.gov` source
   host + key verification** before any text is ingested; agentic results require
   human approval.
-- `/admin/authority/queue` is **read-only and superuser-gated** — it observes the
-  frontier; triggering stays in the enrichment runner.
+- `/admin/authority/queue` (the Authority Console Queue tab) is **superuser-gated**
+  — it observes the frontier and offers per-row requeue/reset/reroute/approve/delete
+  verbs; triggering enrichment runs stays on the Runs tab (`/admin/authority/runs`).

docs/assets/images/screenshots/auto/authorities--sources-monitor--selection.png

@@ -97,6 +97,7 @@ nav:
       - Bulk Import: architecture/bulk-import.md
       - Document Analyzers: architecture/analyzers.md
       - Reference-Web Enrichment & Authority Discovery: architecture/reference-web-enrichment.md
+      - Authority Console: architecture/authority-console.md
       - Discovery System (llms.txt, MCP, robots.txt): architecture/discovery_system.md
       - Corpus Actions: architecture/opencontract-corpus-actions.md
       - Agent Corpus Actions: architecture/agent_corpus_actions_design.md