UAI Explorer

Public-safe documentation and context portal for UAI project material.

The current production build adds local accounts, role and tag separation, curated catalog access, redaction, audit logging, separate human/AI surfaces, and production cutover evidence. Public-safe mode serves curated, redacted catalog material only; legacy raw filesystem and upload endpoints are refused.

Current Status

• Production CT 121 is running UAI Explorer 0.2.3 in public-safe mode.
• Sandbox CT 126 remains the staging and verification lane on 0.2.3.
• Internal production cutover is complete; no DNS/TLS/firewall/reverse-proxy, NetBird, or public-route changes were made.
• Open public-safe v1 decisions: 0.
• Final status: Finish Status Packet
• Cutover evidence: Production Cutover Evidence

Scope

UAI Explorer owns:

• Local account bootstrap, login, sessions, roles, and tag grants.
• Curated documentation catalog entries.
• Redacted human reader UI.
• Bounded AI context endpoints.
• Admin user, catalog, audit, and readiness surfaces.
• Audit records for access decisions.
• Private lab-only legacy file inspection and upload paths when PUBLIC_SAFE_MODE=false.

UAI Explorer does not own:

• Mesh node management (uai-mesh).
• Infrastructure control plane (uai-switchboard).
• User gateway or community features (UAPI, uai-portal, uai-web).
• Discord bot or orchestration (uai-discord-bot).
• DNS, TLS, firewall, or public route cutover.

Features

• Login And Sessions: local users with PBKDF2 password hashes and HttpOnly session cookies.
• Tags And Roles: human, AI, and admin roles with project tags such as cortex, docs, and code.
• Curated Catalog: allowlisted documentation entries instead of public raw filesystem traversal.
• Explorer 2.0 Dashboard Slice: device survey map, drift warnings, Cadence lineage, relationship map, idea inbox, review queue, safe operating loop, context stack, and feature clone radar.
• Mode-Governed Navigation: sidebar grouping separates human work, AI context surfaces, and admin operations.
• Command Surface: dashboard search over safe destinations, authorized catalog entries, and operator lanes without raw filesystem exposure.
• Collection Shelf: Outline/BookStack/Docusaurus-inspired organization model for project shelves, standards, archives, runbooks, and restricted raw survey lanes.
• Source Passport: DataHub/OpenMetadata-inspired source profiles showing owner, freshness, trust, lineage notes, access boundary, and next action for device and documentation lanes.
• Survey Intake: Zenbook metadata-only workbench showing topic clusters, file mix, suppressed aliases, and closed survey state without exposing raw content.
• Device Survey Worker: explicit-root metadata survey tool for preserving device documentation candidates without copying raw contents into Explorer.
• Device Survey Index Builder: repeatable public-safe coverage index built from survey metadata and sanitized export manifests, with explicit blocker rows for truly unknown devices.
• Sanitized Survey Export: metadata-only worker that strips raw file aliases and raw source hashes before outside-agent or catalog-planning review.
• Selected Artifact Redaction: private-lane worker that redacts explicitly selected raw files into non-publishable sanitized artifacts and catalog import candidates for operator review.
• Catalog Import Gate: private-lane approval worker that verifies reviewed redacted artifacts before producing import-ready catalog entries.
• Approved Catalog Staging: private-lane staging worker that copies only approved sanitized artifacts into a catalog root and rewrites catalog source_path values for UAI Explorer.
• Staged Catalog Import: explicit --apply database importer that validates staged artifacts, hashes, tags, visibility, and conflicts before writing approved catalog rows.
• Repo Docs Catalog Sync: repeatable worker that publishes public-safe repo Markdown docs into the curated Explorer catalog so runbooks and evidence do not remain local-only.
• Access Layers: permission preview for human, Cortex, code, AI, and admin layers showing grants, blocked surfaces, audit state, and public-safe deny gates.
• Operator Console: saved views and next-action jump targets for Mac standards survey, Cadence salvage, redaction, and context readiness work.
• Documentation Spine: governed catalog, version, conversion, search, and publish stages inspired by Backstage TechDocs, Docusaurus, MkDocs, MarkItDown, Pagefind, and DocSearch.
• Device Documentation Intake: MacBook, Devine, and Cadence standards are treated as survey inputs that must be classified, redacted, and cataloged before public display.
• Redaction: shared redaction before human content, AI packets, audit details, and unsafe raw reads.
• Human UX: professional catalog, reader, context notes, admin, audit, and readiness views using the United AI dark/gold visual theme.
• AI UX: bounded /api/ai/* context packets with audit IDs and character caps.
• AI Bootstrap Contract: /api/ai/bootstrap gives fresh agents the UAI rules, denied surfaces, primary context slugs, and Python/Rust/Axum/C++ development lane notes without exposing raw content.
• AI Task Prompt UX: the AI view and bootstrap contract provide copyable full/quick prompts so operators only specify product, task, authority, and done condition.
• UAI Agent Feedback Lane: /api/ai/feedback lets AI agents optionally leave product-scoped, redacted notes for future patch planning; no feedback means the lane works as-is.
• Migration Readiness: admin evidence checks for sandbox deploy, QA/QC/QoL, rollback rehearsal, and production health.
• Documentation Source Of Truth: Explorer is the canonical documentation surface; local runbooks and start files are caches or drafting lanes until cataloged.
• AI Lane Adapter Contract: MCP-style adapters use only bounded /api/ai/* tools and must not proxy raw filesystem, admin, upload, or database access.

Operational Docs

• Agent Instructions
• AI Start Here
• UAI Lab Device Start Here
• UAI Explorer Rules
• Enterprise Public-Safe v1 Plan
• Explorer 2.0 GitHub Feature Survey
• Explorer 2.0 UX Blueprint
• Explorer 2.0 Redaction And Embedding Lanes
• QA QC QoL Gates
• Sandbox Protocol
• Public-Safe Access Runbook
• Device Documentation Survey Runbook
• Content Promotion Workflow
• Documentation Source Of Truth Runbook
• AI Lanes And MCP Adapter Runbook
• UAI Development Standards Runbook
• UAI Agent Feedback Convention
• AI Memory, Knowledge, Beacon, And Mesh Runbook
• Device AI Start-Here Refresh Runbook
• Proxmox Storage Maintenance Runbook
• Operator Decision Brief
• Device Survey Index
• Historical Migration-Ready Runbook
• Local Verification Evidence
• Local Hardening Evidence
• Explorer 2.0 Design Evidence
• Selected Redaction Worker Evidence
• NUC-IPEX Sanitized Export Evidence
• MacBook-Air Sanitized Export Evidence
• Lab Storage And Device Visibility Evidence
• Lab Node Identity Survey Evidence
• Proxmox Storage Review Evidence
• Content Promotion Packet Evidence
• Catalog Import Gate Evidence
• Approved Catalog Staging Evidence
• Staged Catalog Import Evidence
• Finish Status Packet
• Production Cutover Evidence
• Operator Final Decisions
• Documentation Governance Pass
• Post-Governance Container Sync
• Repo Docs Catalog Sync
• AI Bootstrap Contract Evidence
• Final QA/QoL Punch List Evidence
• Final Completion Audit
• Operator Decision Intake
• Operator Decision Intake Evidence
• Operator Decision Response Template
• Operator Decision Response Validation Evidence
• Completion Audit
• Sandbox Verification Evidence
• Diary Index

Sandbox deployment uses deploy-sandbox.sh. It targets container 126 and refuses to run against production container 121.

API Endpoints

AI Lane / MCP-Equivalent Client Setup

MCP servers and local AI adapters must act as AI clients, not admin clients.

Default operator prompt:

UAI_EXPLORER_ENDPOINT: http://10.0.0.121:8080
UAI_EXPLORER_AI_API_KEY: <paste AI API key here>

Use UAI Explorer as your source of truth for UAI rules, lab boundaries, docs, and project context.

If adapter tools are available, use them. If HTTP is required, send the API key as Authorization: Bearer <UAI_EXPLORER_AI_API_KEY>.

Authenticate through the UAI Explorer AI lane, run uai_ready, run uai_bootstrap, fetch the required primary_context entries marked accessible_to_session=true, then complete this task:

Product: <uai-explorer | cortex | beacon | mesh | cadence | devine | other>
Task: <specific outcome>
Authority: <plan only | local repo work allowed | sandbox work allowed | production read-only>
Done when: <clear acceptance criteria>

Follow UAI rules and sandbox protocol. Do not use admin, raw file, upload, SQLite, .env, .ssh, device filesystem, or public exposure surfaces unless I explicitly authorize a separate runbook. If the API key is missing or rejected, stop and say UAI Explorer AI-lane access is not provisioned. If context is missing or the UX blocks you, leave safe product-scoped feedback through uai_submit_feedback.

Quick operator prompt:

UAI_EXPLORER_ENDPOINT: http://10.0.0.121:8080. UAI_EXPLORER_AI_API_KEY: <paste key>. Use UAI Explorer, follow UAI rules, sync through uai_bootstrap or Authorization: Bearer API key HTTP, then do: <task>. Product: <product>. Authority: <authority>. Done when: <acceptance>.

Allowed adapter tools:

• uai_ready: check /ready and refuse work unless public-safe readiness is clean.
• uai_bootstrap: call /api/ai/bootstrap and follow the returned required rules, denied surfaces, and primary context slugs.
• uai_list_ai_catalog: call /api/ai/catalog.
• uai_get_ai_context: call /api/ai/context/{slug}.
• uai_submit_feedback: optionally call /api/ai/feedback with a product field and beneficial, not-working, missing-context, QoL, blocked, or consider notes.
• uai_search_ai_catalog: optional search over already returned AI-visible catalog metadata.

Adapters must authenticate with a dedicated role=ai Explorer user, keep credentials outside the repo and docs, hold session cookies only in memory or an OS secret store, and reject raw filesystem, upload, admin, SQLite, and generic HTTP proxy behavior.

Basic endpoint-plus-key lane: admins may issue a short-lived AI API key for an existing role=ai user with POST /api/admin/access-tokens. The returned key is visible once, inherits that AI user's tags, is used as Authorization: Bearer <key>, and can be revoked with PATCH /api/admin/access-tokens/{id}. Do not issue AI API keys for admin users. vNext should move to task-bound delegation and one-time exchange instead of prompt-pasted API keys.

Role ai users automatically receive the bootstrap starter docs tags required to fetch the UAI rules, start-here packet, runbooks, QA, plan, and evidence context. Operators add only product/task tags such as cortex, mesh, cadence, or code.

Before returning any packet to an AI worker, the adapter must verify:

• /ready reports status=ready and public_safe_mode=true,
• raw downloads, legacy file APIs, and uploads are disabled,
• raw_survey_zone_mounted=false,
• /api/ai/bootstrap returns kind=uai-ai-bootstrap and includes uai_bootstrap, uai_submit_feedback, and task_prompt_contract,
• context packets include redaction_boundary=server-side, raw_available_to_client=false, char_cap, and audit_event_id.

Agent closeout should include catalog slugs used, audit IDs for fetched context, tests or readiness checks run, changes made or planned, blockers, and feedback submitted or that no feedback was needed.

AI feedback must not contain credentials, session cookies, tokens, private paths, raw content, or direct personal/contact/payment data. Feedback is append-only; do not edit another agent's feedback. No feedback means the current lane works as-is.

Detailed setup: AI Lanes And MCP Adapter Runbook.

Configuration

Environment variables:

Deployment Targets

Production

• Container: CT 121
• IP: 10.0.0.121
• Current version: 0.2.3
• Status: production, public-safe, internal route

Sandbox

• Container: CT 126
• IP: 10.0.0.126
• Current version: 0.2.3
• Status: staging and verification
• Rollback rehearsal snapshot: mr022g-20260620-191542

Local Verification

python -m py_compile server.py tests\test_public_safe.py tools\sanitize_survey_export.py tests\test_sanitized_export.py tools\redact_selected_artifacts.py tests\test_redact_selected_artifacts.py tools\survey_device_documents.py tests\test_survey_device_documents.py tools\build_device_survey_index.py tests\test_build_device_survey_index.py tools\build_content_promotion_packet.py tests\test_content_promotion_packet.py tools\prepare_catalog_import.py tests\test_prepare_catalog_import.py tools\stage_approved_catalog.py tests\test_stage_approved_catalog.py tools\import_staged_catalog.py tests\test_import_staged_catalog.py tools\build_finish_status_packet.py tests\test_build_finish_status_packet.py tools\build_operator_decision_packet.py tests\test_build_operator_decision_packet.py tools\validate_operator_decision_response.py tests\[REDACTED:high-entropy].py
python -m unittest discover -s tests -v
python tools\build_finish_status_packet.py --repo-root . --out-json docs\evidence\uai-explorer-finish-status-2026-06-20.json --out-md docs\evidence\uai-explorer-finish-status-2026-06-20.md
python tools\build_operator_decision_packet.py --finish-status docs\evidence\uai-explorer-finish-status-2026-06-20.json --out-json docs\review\operator-decision-intake-2026-06-20.json --out-md docs\review\operator-decision-intake-2026-06-20.md
python tools\validate_operator_decision_response.py --intake docs\review\operator-decision-intake-2026-06-20.json --response docs\review\[REDACTED:high-entropy].json --out docs\review\operator-decision-validation-2026-06-20.json
python tools\sync_repo_docs_catalog.py --repo-root . --data-root <catalog-data-root> --db <uai-explorer.sqlite3> --out docs\evidence\repo-docs-catalog-sync-2026-06-21.json --apply
node --check static\js\app.js
& "C:\Program Files\Git\bin\bash.exe" -n deploy-sandbox.sh

Project Structure

uai-explorer/
  server.py
  requirements.txt
  .env.example
  START_HERE_AI.md
  START_HERE_UAI_LAB.md
  deploy-sandbox.sh
  uai-explorer.service
  static/
    index.html
    css/style.css
    js/app.js
  tests/
    test_public_safe.py
    test_redact_selected_artifacts.py
    test_sanitized_export.py
    test_survey_device_documents.py
    test_build_device_survey_index.py
    test_content_promotion_packet.py
    test_prepare_catalog_import.py
    test_stage_approved_catalog.py
    test_import_staged_catalog.py
    test_sync_repo_docs_catalog.py
    test_build_finish_status_packet.py
    test_build_operator_decision_packet.py
    [REDACTED:high-entropy].py
  tools/
    build_device_survey_index.py
    build_content_promotion_packet.py
    prepare_catalog_import.py
    redact_selected_artifacts.py
    stage_approved_catalog.py
    import_staged_catalog.py
    sync_repo_docs_catalog.py
    build_finish_status_packet.py
    build_operator_decision_packet.py
    validate_operator_decision_response.py
    sanitize_survey_export.py
    survey_device_documents.py
  docs/
    diary/
    evidence/
    plans/
    qa/
    review/
    runbooks/

Current Ops Notes

• Production CT 121 is cut over and public-safe internally.
• CT 126 remains the staging lane for future changes.
• External exposure still requires a separate DNS/TLS/firewall/reverse-proxy runbook.
• Do not write credential values into docs, diaries, tickets, or audit evidence. The transient prompt exception is a short-lived UAI_EXPLORER_AI_API_KEY issued for a role=ai user; do not persist it.
• Do not leave important UAI documentation local-only. Catalog it in Explorer or mark it private/superseded with a clear reason.