# Admin Panel Source Management Future Direction

Issue: #235

Status: future design stub only. This document does not implement an admin panel, change runtime behavior, change source enablement, or change deployment configuration.

## Why An Admin Panel Is Needed

The current source-grounded assistant work is governed through files, issues, PRs, validation scripts, receipts, and deployment configuration. That is appropriate for early hardening, but it is not the long-term operator experience for source management.

Future non-developer administrators may need to review source status, see freshness posture, understand what is enabled, initiate approved changes, and inspect receipts without living in Codex, Git, or an IDE.

The admin panel should reduce operational friction without weakening governance.

## User Roles

Candidate roles:

- Package owner: approves canonical package changes and source authority changes.
- Source steward: reviews candidate sources, freshness, owner metadata, and allowed path constraints.
- Runtime operator: confirms deployment posture, smoke status, and rollback readiness.
- Reviewer: inspects candidate updates and source divergence before approval.
- Auditor: reads receipts, change history, and source-lane evidence.
- Read-only stakeholder: views status without changing configuration.

Role names are placeholders. Actual authorization design requires a separate issue.

## Source Management Capabilities

A future panel may show or manage:

- source registry entries
- source approval status
- source enable/disable state
- source priority
- source type
- trust labels
- freshness labels
- claim boundaries
- allowed origins
- allowed path prefixes
- source owner metadata
- proposed approver metadata
- review due dates
- latest smoke result
- latest retrieval timestamp
- rollback instructions
- candidate-only versus enabled status
- package authority status
- link to receipts and PRs

The panel should distinguish candidate-only, deferred, rejected, owner-approved, enabled current/public, and approved package authority. Those are different states.

## Governance Constraints

The admin panel must preserve these constraints:

- Package-only remains default.
- Package authority changes require human review.
- Current/public source changes require explicit source-lane labels.
- Current/public sources do not become package authority by being enabled.
- Source enablement requires owner approval, deployment control, smoke evidence, and rollback evidence.
- Runtime configuration changes are not silently made by browsing a page.
- Every meaningful change has issue, PR, validation, receipt, or deployment-action evidence.

## No Silent Authority Mutation

The panel must never silently rewrite source authority.

If an administrator identifies a needed package change, the panel should create or link to a controlled update candidate. That candidate should include:

- package citation
- current/public citation, if applicable
- divergence or gap summary
- proposed package change
- affected files or sections
- owner review status
- validation and receipt expectations

The package changes only after approved repo workflow completes.

## No Direct Secret Exposure

The panel may display secret names and configuration posture when safe, but it must not display secret values.

Safe examples:

- `AICD_PROVIDER_API_KEY`: configured as encrypted server-side secret
- `AICD_CURRENT_CONTEXT_ADAPTER`: configured
- `AICD_CURRENT_CONTEXT_SOURCE_REGISTRY_JSON`: configured

Unsafe examples:

- raw provider API key values
- raw registry secret values when they are stored outside repo as deployment secrets
- bearer tokens
- Cloudflare API tokens
- service tokens
- session cookies
- private headers

Secret handling needs separate security review before implementation.

## Change-Control Integration

The panel should integrate with change control instead of bypassing it.

Possible controlled outputs:

- create source review issue
- create source enablement issue
- create package update candidate issue
- open a PR with generated registry changes
- attach validation receipt draft
- link to deployment runbook
- link to rollback instructions
- record approval status
- trigger a smoke test only where separately authorized

The safest default is that the panel proposes changes and records evidence. It should not directly mutate production authority.

## Possible Future Workflows

### Source Candidate Review

1. Admin adds a candidate URL.
2. Panel validates HTTPS, origin, path prefix, credentials, and private-host constraints.
3. Panel creates a candidate review issue or PR.
4. Human reviewer approves, defers, or rejects.
5. Candidate remains disabled until a later enablement issue.

### Source Enablement

1. Admin selects an approved candidate.
2. Panel checks owner authorization, review freshness, path constraints, and rollback plan.
3. Panel creates an enablement request and required receipt template.
4. Runtime operator performs deployment-controlled config change outside the repo.
5. Smoke results are recorded.
6. Source state changes only after evidence is present.

### Divergence Review

1. Assistant or watch loop identifies package/current divergence.
2. Panel shows package citation and current/public citation in separate lanes.
3. Reviewer marks as no action, package update candidate, source issue, or policy-sensitive review.
4. Approved package updates go through normal repo workflow.

### Refresh Watch

1. Curated source is checked on a cadence.
2. Panel displays freshness, last retrieval timestamp, and detected change summary.
3. Material changes become review candidates.
4. No package text changes without human approval.

## Open Questions

- Which identity provider and role model should protect the panel?
- Which actions are read-only, proposal-only, PR-generating, or deployment-triggering?
- What minimum receipt is required for source enablement?
- Where should admin action history live before durable telemetry is approved?
- How should watch-loop evidence be retained without adding a database?
- Which source states belong in repo JSON versus deployment configuration?
- How should rollback be represented for non-developer operators?
- What provider/model display metadata is safe and useful?
- How should the panel present candidate-only sources so users do not mistake them for enabled sources?

## Explicit Non-Goals

This design stub does not:

- implement an admin panel
- add authentication or authorization
- add a database
- add durable telemetry
- add vector storage
- add Supabase
- add uploads or session attachments
- expose secrets
- change runtime behavior
- change Cloudflare env/config
- change Cloudflare Access/WAF
- change provider/model secrets or provider/model config
- enable or disable any source
- promote current/public sources into package authority