SPEC.md — Atlas AI Governance Platform > Working name: **Atlas** > Purpose: internal AI Governance platform for governing AI tools, coding agents, personal plans, gateway-routable agents, policy decisions, cost attribution, and audit evidence. --- 1. Product summary Atlas is an internal AI Governance control plane for organizations where developers and employees use multiple AI tools and coding agents, including: Enterprise / Team / Business SaaS tools such as ChatGPT, Claude, Cursor, GitHub Copilot. Gateway-routable coding agents such as Claude Code, Codex CLI, OpenCode, OpenHands, Pi, Droid-like tools. Existing company-funded personal plans that are currently in use but should be migrated or tightly controlled. Evidence sources such as AgentsView, gateway logs, provider usage reports, SaaS admin usage, expense reimbursements, MDM inventory, CASB/SWG logs, and Git repository metadata. Atlas does not try to make AgentsView the governance system. AgentsView remains an evidence/session viewer. Atlas becomes the source of truth for policy, registry, approval, exception, cost attribution, and compliance state. Primary goals Standardize AI tools into clear statuses: `official` `experimental` `transition_personal` `prohibited` Know the AI operating cost of a project as accurately as possible: Exact when traffic flows through gateway or provider-native project/workspace billing. Allocated/estimated when usage is subscription-based or personal-plan-based. Enforce policy at the correct layers: SSO / IdP for identity and account access. CASB / SWG / DNS / firewall for SaaS and domain/network access. MDM / EDR / endpoint rules for app install/use control. AI Gateway for request-level, model-level, project-level, and budget-level controls. AgentsView only for evidence, session discovery, transcript search, and local cost estimates. Provide a single place to answer: Which AI tools are allowed? Who is using which tool? Which projects are using AI? Which models/providers are being used? What is the AI cost per project? Which usage is verified vs merely discussed? Which personal plans still exist and when do they expire? Which policy decisions blocked or allowed AI usage? Non-goals Atlas is not: A replacement for AgentsView. A replacement for CASB/SWG/MDM/IdP. A universal gateway for every AI tool. A magic blocker for tools that do not support base URL, proxy, enterprise SSO, or managed configuration. A source of truth for model pricing unless it ingests pricing from gateway/provider/model maps. A place to store raw sensitive prompts by default without retention and access policy. --- 2. Core use cases 2.1 Register and classify AI tools As a platform/security owner, I can register tools and classify them. Example statuses: ```yaml tool: claude-code status: official runtime_type: gateway_routable_agent allowed_groups: - ai-engineering allowed_projects: - all_engineering_projects allowed_models: - claude-sonnet - claude-haiku policy_owner: ai-governance-team review_cycle_days: 90 ``` ```yaml tool: cursor-pro-personal status: transition_personal runtime_type: personal_subscription allowed_groups: - ai-transition-users expiry_date: 2026-09-30 migration_target: cursor-business-or-gateway-routable-agent ``` ```yaml tool: random-ai-browser-extension status: prohibited block_strategy: - mdm_extension_block - casb_domain_block - swg_category_block ``` 2.2 Manage personal-plan transition As a company, we may currently pay for personal AI plans. Atlas must track them explicitly. Personal plans should be treated as: ```text company-funded personal AI = transition / exception state company-funded personal AI != official governed tool ``` Required fields: User. Tool. Account email. Payment source. Projects used. Allowed data classes. Forbidden data classes. Expiry date. Migration target. Monthly cost. Approval owner. 2.3 Enforce gateway-routable agent policy For agents that support `base_url`, custom provider, or proxy configuration, Atlas should generate and sync gateway policy. Example: ```text Claude Code / Codex CLI / OpenCode -> configured to call ai-gateway.company.com -> gateway checks project_id, user_id, model, budget -> gateway logs request/cost/policy decision -> Atlas ingests logs ``` The developer should not hold provider API keys. Instead: ```text Developer -> SSO -> internal token / virtual key -> AI Gateway -> provider credential vault -> model provider ``` 2.4 Govern enterprise SaaS AI tools For SaaS tools that do not route through the AI Gateway, Atlas manages policy via external control systems: SSO groups. Enterprise tenant configuration. CASB/SWG rules. MDM app/extension rules. Vendor admin dashboards. Expense and procurement data. Cost is not always exact. It is often: ```text seat cost + vendor usage + AgentsView estimate + allocation rules ``` 2.5 Produce project-level AI cost Atlas should compute multiple cost views: Exact gateway cost. Provider-native project/workspace cost. SaaS seat allocation. Personal plan reimbursement allocation. AgentsView session cost estimate. Unknown/unattributed cost. A project cost view must clearly label confidence: ```text verified_exact verified_provider_reported estimated_from_sessions allocated_from_seat_cost self_reported unknown ``` 2.6 Ask audit questions Examples: “Which projects used prohibited tools last month?” “Who still has personal AI plans?” “Which users used Cursor personal for company work?” “What did Project A spend on AI this month?” “Which requests were blocked by policy?” “Which models did Project B use?” “Show all evidence supporting this cost number.” 2.7 Evidence-first investigation Atlas should never show a conclusion without evidence. For every answer: ```text claim -> evidence -> confidence -> source -> timestamp ``` --- 3. Product Shape Atlas is composed of four major surfaces. 3.1 Governance Portal A web UI for administrators, platform engineers, security, finance, and team leads. Pages: Dashboard. Tool Registry. Model Registry. Provider Registry. Project Registry. Policy Registry. Personal Plan Declarations. Exception Requests. Cost Explorer. Evidence Explorer. Policy Decision Logs. Control Sync Status. Ask Atlas. 3.2 Control Plane API A Python FastAPI service that provides: CRUD for registry objects. Approval workflow APIs. Policy evaluation APIs. Cost query APIs. Evidence query APIs. Integration APIs. Gateway adapter APIs. CLI backend APIs. 3.3 Workers and Integrations Background workers sync policies and ingest evidence. Workers: SSO group sync. CASB/SWG blocklist sync. MDM app policy sync. LiteLLM config/key/budget sync. AgentsView ingestion. Provider usage ingestion. Expense ingestion. Cost attribution job. Evidence extraction job. Policy bundle build job. 3.4 CLI A CLI for developers and platform engineers. Use cases: Register local agent configuration. Validate compliance status. Configure gateway-routable agents. Declare current personal plan. Check project budget. Install or check AgentsView collection. --- 4. Design Laws Law 1 — Policy before view Policy must be enforced before evidence is viewed. AgentsView is not the enforcement layer. It is evidence after the fact. Law 2 — Official tools must have a control surface A tool can be official only if it has at least one strong control surface: Enterprise/team/business admin controls such as SSO, offboarding, member management, policy, and usage visibility. Gateway routeability such as `base_url`, proxy, custom provider, or API gateway support. If neither exists, the tool cannot be official. Law 3 — Personal plans are temporary Company-funded personal plans are not official. They are: ```text transition_personal ``` They require: Declaration. Approval. Expiry date. Data restrictions. Migration target. Reimbursement control. Law 4 — Gateway is not universal Gateway controls only requests that pass through it. Gateway is correct for: Model allowlists. Project budgets. Rate limits. API cost tracking. Request audit. DLP-style request checks if traffic passes through gateway. Gateway is not correct for: Blocking a user from opening a prohibited app. Blocking personal account login. Controlling tools that do not support base URL/proxy/custom provider. Law 5 — Hooks are optional defense-in-depth Agent hooks must never be the only control. Some agents do not support hooks. Hooks can help with: Pre-tool checks. Secret scanning. Local repo safety. Developer UX. Core policy must be enforced by: SSO/CASB/MDM/EDR. Gateway. Provider admin controls. Procurement/expense policy. Law 6 — Every claim must have evidence Atlas must distinguish: Discussed. Self-reported. Observed. Verified. Enforced. Blocked. Law 7 — No developer provider API keys by default Developers should not hold provider API keys for official gateway-routable workflows. Preferred model: ```text SSO -> internal token -> AI Gateway -> provider credential vault -> provider ``` Law 8 — Unknown is a first-class state Atlas must not fake certainty. If cost, usage, policy, or ownership is unknown, it must be labeled as unknown. Law 9 — Evidence may be sensitive Prompt/session evidence may contain source code, secrets, customer data, or confidential context. Evidence retention and access must be governed separately. Law 10 — Docker-first developer experience All core services should run locally with Docker Compose. A new engineer should be able to run: ```bash docker compose up ``` and get: API. Web app. Postgres. Redis. OPA. LiteLLM. Workers. Optional ClickHouse. Optional AgentsView integration. --- 5. Technical Architecture 5.1 High-level architecture ```text ┌──────────────────────────────────────────────────────────────────┐ │ Atlas Governance Portal │ │ │ │ Tool Registry | Model Registry | Project Budgets | Exceptions │ │ Cost Explorer | Evidence Explorer | Ask Atlas │ └───────────────────────────────┬──────────────────────────────────┘ │ v ┌──────────────────────────────────────────────────────────────────┐ │ Atlas Control Plane API │ │ Python FastAPI │ │ │ │ Registry API | Policy API | Cost API | Evidence API │ │ Approval API | Integration API | CLI API │ └───────────────┬───────────────────────────────┬──────────────────┘ │ │ v v ┌─────────────────────────────┐ ┌─────────────────────────────┐ │ PostgreSQL │ │ OPA │ │ │ │ Rego Policy │ │ Registry source of truth │ │ │ │ Approvals │ │ allow tool? │ │ Exceptions │ │ allow model? │ │ Budgets │ │ budget ok? │ │ Users/projects/tools │ │ data class ok? │ └─────────────────────────────┘ └──────────────┬──────────────┘ │ v ┌──────────────────────────────────────────────────────────────────┐ │ Control Sync Workers │ │ Celery/Dramatiq for MVP, Temporal later │ │ │ │ Sync policy to SSO, CASB, MDM, DNS, firewall, LiteLLM │ │ Ingest evidence from AgentsView, provider usage, expenses │ └───────────────────────────────┬──────────────────────────────────┘ │ v ┌──────────────────────────────────────────────────────────────────┐ │ Runtime Layer │ │ │ │ Track A: Enterprise SaaS AI │ │ SSO/CASB/MDM governed │ │ │ │ Track B: Gateway-routable coding agents │ │ LiteLLM / AI Gateway governed │ │ │ │ Track C: Personal plan transition │ │ Declaration + restrictions + reimbursement control │ └───────────────────────────────┬──────────────────────────────────┘ │ v ┌──────────────────────────────────────────────────────────────────┐ │ Evidence & Cost Layer │ │ │ │ ClickHouse / Postgres analytics │ │ Gateway logs │ │ AgentsView sessions │ │ Provider usage │ │ SaaS seat cost │ │ Expense reimbursement │ │ Policy decision events │ └──────────────────────────────────────────────────────────────────┘ ``` 5.2 Docker development topology ```text atlas-dev ├── web-admin Next.js ├── api FastAPI ├── worker Celery/Dramatiq worker ├── postgres Registry DB ├── redis Queue/cache ├── opa Policy engine ├── litellm Local AI Gateway ├── clickhouse Optional analytics DB ├── otel-collector Optional telemetry collector └── agentsview Optional evidence/session viewer ``` Example services: ```yaml services: web: build: ./apps/web ports: - "3000:3000" api: build: ./apps/api ports: - "8000:8000" depends_on: - postgres - redis - opa worker: build: ./apps/api command: celery -A atlas.worker worker -l info depends_on: - postgres - redis postgres: image: postgres:16 redis: image: redis:7 opa: image: openpolicyagent/opa:latest litellm: image: ghcr.io/berriai/litellm:main-latest clickhouse: image: clickhouse/clickhouse-server:latest ``` 5.3 Core services API Service Responsibilities: Registry CRUD. Policy evaluation endpoint. Approval workflow. Evidence query. Cost query. CLI support. Integration coordination. Policy Service Can be part of API initially. Responsibilities: Build OPA bundles. Validate Rego policy. Evaluate policy decisions. Store policy decision logs. Version policies. Control Sync Worker Responsibilities: Push allowed/prohibited tools to enforcement systems. Generate LiteLLM config or call LiteLLM Admin API. Sync project budgets to gateway. Sync user/group membership from IdP. Generate blocklist exports. Cost Ledger Worker Responsibilities: Ingest gateway logs. Ingest provider usage. Ingest AgentsView session usage. Ingest expense data. Attribute cost to project. Produce verified/estimated/allocated cost records. Evidence Extractor Responsibilities: Normalize raw evidence. Extract entities. Generate evidence graph edges. Separate discussed vs verified claims. Agent Bootstrap CLI Responsibilities: Configure local agent base URLs. Validate compliance. Register project/tool usage. Check current user policy. Help migrate from personal plans. --- 6. Tech stack 6.1 Chosen MVP stack ```text Language: Python 3.12+ Backend: FastAPI Pydantic v2 SQLAlchemy 2.x Alembic httpx Frontend: Next.js React TypeScript shadcn/ui TanStack Query Tailwind CSS Database: PostgreSQL 16+ Queue: Redis Celery or Dramatiq Policy: Open Policy Agent Rego Gateway: LiteLLM Proxy Analytics: PostgreSQL for MVP ClickHouse for high-volume events later CLI: Typer Rich Observability: OpenTelemetry structlog Prometheus-compatible metrics Deployment: Docker Compose for development Kubernetes + Helm later Secrets: Local .env for development Vault or cloud secret manager later ``` 6.2 Why Python instead of NestJS Python is preferred for this product because core work involves: AI infrastructure integration. Log ingestion. Cost calculation. Policy sync automation. CLI tooling. Data extraction. LiteLLM integration. Provider usage processing. NestJS remains valid, but Python is more aligned with the AI infra and data processing surface of this product. 6.3 Libraries and packages Backend: ```text fastapi uvicorn pydantic pydantic-settings sqlalchemy alembic psycopg httpx python-jose or authlib structlog opentelemetry-api opentelemetry-sdk ``` Workers: ```text celery redis or dramatiq or temporalio later ``` CLI: ```text typer rich httpx pydantic ``` Analytics: ```text clickhouse-connect pandas only for offline scripts, not core runtime ``` Testing: ```text pytest pytest-asyncio respx factory-boy ruff mypy ``` 6.4 Repository layout ```text atlas/ ├── SPEC.md ├── README.md ├── docker-compose.yml ├── .env.example ├── Makefile │ ├── apps/ │ ├── api/ │ │ ├── atlas_api/ │ │ │ ├── main.py │ │ │ ├── config.py │ │ │ ├── auth/ │ │ │ ├── db/ │ │ │ ├── registry/ │ │ │ ├── policy/ │ │ │ ├── evidence/ │ │ │ ├── cost/ │ │ │ ├── integrations/ │ │ │ └── telemetry/ │ │ ├── tests/ │ │ └── pyproject.toml │ │ │ ├── worker/ │ │ ├── atlas_worker/ │ │ │ ├── app.py │ │ │ ├── tasks/ │ │ │ └── pipelines/ │ │ └── pyproject.toml │ │ │ ├── cli/ │ │ ├── atlas_cli/ │ │ │ ├── main.py │ │ │ ├── commands/ │ │ │ └── output.py │ │ └── pyproject.toml │ │ │ └── web/ │ ├── app/ │ ├── components/ │ ├── lib/ │ └── package.json │ ├── packages/ │ ├── policy-schemas/ │ ├── example-data/ │ └── shared-contracts/ │ ├── policies/ │ ├── tools.rego │ ├── models.rego │ ├── budgets.rego │ ├── data_classes.rego │ └── exceptions.rego │ ├── infra/ │ ├── docker/ │ ├── helm/ │ └── terraform/ │ └── docs/ ├── architecture.md ├── policy-model.md ├── evidence-model.md └── cost-model.md ``` --- 7. Struct extraction strategy Atlas needs to transform many unstructured and semi-structured inputs into structured governance facts. 7.1 Input sources Registry inputs Tool registry records. Model registry records. Project registry records. User/group records. Policy definitions. Exception records. Runtime inputs LiteLLM request logs. Gateway allow/block events. AgentsView session data. Provider usage exports. SaaS admin usage reports. MDM app inventory. CASB/SWG access logs. DNS/firewall block events. Expense reimbursement reports. Git repository metadata. Human inputs Personal plan declarations. Project ownership declarations. Tool review notes. Security review notes. Exception approvals. 7.2 Extraction pipeline ```text Raw source -> source-specific parser -> normalized evidence event -> entity extraction -> confidence scoring -> graph edge generation -> cost attribution -> audit query index ``` 7.3 Normalized evidence event ```json { "event_id": "evt_01H...", "event_type": "ai_request_allowed", "source": "litellm", "source_record_id": "req_123", "timestamp": "2026-06-15T10:00:00Z", "actor": { "user_id": "alice@company.com", "device_id": "device-123" }, "tool": { "tool_id": "claude-code", "runtime_type": "gateway_routable_agent" }, "project": { "project_id": "project-a", "repo": "github.com/company/project-a" }, "model": { "provider": "anthropic", "model_id": "claude-sonnet" }, "policy": { "decision": "allow", "policy_version": "2026.06.15-1", "matched_rules": ["official_tool", "budget_ok", "model_allowed"] }, "usage": { "input_tokens": 12000, "output_tokens": 2500, "cost_usd": 0.123 }, "confidence": "verified_gateway", "sensitivity": "internal" } ``` 7.4 Extraction confidence levels ```text verified_gateway: From gateway logs, policy decisions, token usage, cost logs. verified_provider: From provider usage/billing export. verified_admin: From IdP, MDM, CASB, SaaS admin APIs. observed_local: From AgentsView/session logs/local files. self_reported: From user declaration or form. inferred: Derived by heuristics, mapping, or allocation. discussed: Mentioned in transcript/message but not confirmed. unknown: No reliable evidence. ``` 7.5 Entity extraction rules Extract the following entities: User. Group. Device. Tool. Agent. Model. Provider. Project. Repository. Session. Request. Policy decision. Cost record. Evidence item. Exception. Approval. Data class. 7.6 Mapping sessions to projects Priority order: Explicit `project_id` in gateway metadata. CLI config project ID. Git remote URL. Working directory mapping. AgentsView project field. User declaration. Heuristic inference. Unknown. 7.7 Mapping cost to projects Priority order: Gateway exact cost by `project_id`. Provider-native project/workspace billing. SaaS admin usage by user/team/project if available. AgentsView session estimate by repo/project. Seat cost allocation by declared project usage. Expense allocation. Unknown/unattributed. --- 8. From Evidence to Graph Atlas should maintain an evidence graph to connect people, tools, projects, sessions, models, policies, and cost. 8.1 Graph purpose The graph answers questions such as: Which users used a prohibited tool? Which projects used experimental models? Which evidence supports Project A's cost? Which personal plans are linked to production repositories? Which blocked requests were caused by model policy? Which sessions discussed secrets vs actually sent secrets to a provider? 8.2 Graph model Nodes: ```text User Group Device Tool Agent Model Provider Project Repository Session Request PolicyDecision CostRecord EvidenceItem Exception Approval DataClass ``` Edges: ```text User BELONGS_TO Group User USES Tool User OWNS PersonalPlan Tool HAS_STATUS ToolStatus Tool ROUTES_THROUGH Gateway Agent GENERATES Session Session BELONGS_TO Project Session TOUCHES Repository Request USES Model Model SERVED_BY Provider Request HAS_POLICY_DECISION PolicyDecision Request PRODUCES CostRecord EvidenceItem SUPPORTS CostRecord EvidenceItem SUPPORTS PolicyDecision Exception ALLOWS Tool Approval APPROVES Exception Project HAS_BUDGET Budget ``` 8.3 Graph storage strategy MVP: Store graph as relational tables in PostgreSQL. Store edges in a generic `graph_edges` table. Store evidence events in PostgreSQL first. Production: Keep registry in PostgreSQL. Store high-volume events in ClickHouse. Materialize graph views for query performance. Consider Neo4j only if graph queries become central and relational/ClickHouse are insufficient. 8.4 Evidence graph schema ```sql create table graph_nodes ( id text primary key, node_type text not null, display_name text not null, properties jsonb not null default '{}', created_at timestamptz not null default now(), updated_at timestamptz not null default now() ); create table graph_edges ( id text primary key, from_node_id text not null references graph_nodes(id), to_node_id text not null references graph_nodes(id), edge_type text not null, evidence_id text, confidence text not null, properties jsonb not null default '{}', created_at timestamptz not null default now() ); ``` 8.5 Graph query examples ```text Find all projects with personal-plan evidence: Project <-BELONGS_TO- Session <-GENERATES- Agent <-USES- User ->OWNS PersonalPlan ``` ```text Find all policy blocks for a project: Project <-BELONGS_TO- Request ->HAS_POLICY_DECISION PolicyDecision(decision=block) ``` ```text Find cost evidence: Project <-BELONGS_TO- CostRecord <-SUPPORTS- EvidenceItem ``` --- 9. Separate Discussed vs verified This is one of the most important product rules. A transcript may say: ```text "We should use Cursor Pro for Project A." ``` This is only `discussed`. It is not verified until Atlas sees one of: Gateway request logs. AgentsView session mapped to Project A. Cursor admin usage. Personal plan declaration. Expense reimbursement. MDM/CASB event. User approval record. 9.1 Evidence states ```text discussed: Mentioned in a chat/session/transcript. self_reported: Declared by user or admin. observed: Seen in a log or local session, but not authoritative. verified: Confirmed by authoritative system. enforced: Policy was applied by a control system. blocked: A request/access/tool was denied. unknown: No evidence. ``` 9.2 UI requirement Every UI answer must show status badges: ```text Discussed Self-reported Observed Verified Enforced Blocked Estimated Allocated Unknown ``` 9.3 Cost confidence labels ```text Exact: Gateway/provider billing exact. Provider-reported: Provider dashboard/export. Estimated: From AgentsView token/session estimate. Allocated: Seat or personal plan cost split across projects. Self-reported: User/team declaration. Unknown: No reliable attribution. ``` 9.4 Ask Atlas requirement Ask Atlas must never answer: ```text "Project A used Cursor." ``` without qualifying it: ```text "Project A has observed AgentsView session evidence for Cursor usage, but no verified vendor/gateway billing record. Confidence: observed_local." ``` --- 10. Roadmap Phase 0 — Repo and Docker foundation Deliverables: Repo initialized. Docker Compose running. FastAPI service. Postgres. Redis. OPA. LiteLLM local service. Basic Next.js app. Basic CLI skeleton. Exit criteria: ```bash docker compose up ``` brings up the local stack. Phase 1 — Registry MVP Deliverables: Tool registry. Model registry. Project registry. Personal plan declarations. Basic approval state. PostgreSQL schema and Alembic migrations. Seed data. CLI commands for registry list/get. Exit criteria: Admin can classify tools as official/experimental/prohibited/transition_personal. User can declare personal plan. Phase 2 — Policy MVP Deliverables: OPA integration. Rego policies for tools/models/projects/budgets. Policy decision endpoint. Decision logs. CLI `atlas policy check`. Exit criteria: Atlas can answer allow/block for a tool/model/project/user input. Phase 3 — Gateway MVP Deliverables: LiteLLM local integration. Generate virtual key or config from registry. Project/model allowlist sync. Gateway log ingestion. Request-level cost event. Exit criteria: One gateway-routable agent can send requests through LiteLLM. Atlas can ingest and show cost by project. Phase 4 — AgentsView evidence MVP Deliverables: AgentsView data ingestion adapter. Session to project mapping. Evidence event normalization. Session evidence explorer. Exit criteria: Atlas can show local coding sessions and map them to project/repo. Phase 5 — Personal plan governance Deliverables: Personal plan declaration UI. Expiry and approval workflow. Expense import CSV. Cost allocation rule. Exit criteria: Personal plan cost can be allocated to projects with confidence label. Phase 6 — Website MVP Deliverables: Dashboard. Tool registry UI. Project cost UI. Evidence explorer UI. Policy decision log UI. Personal plan UI. Exit criteria: Stakeholders can use web UI without CLI. Phase 7 — Ask Atlas MVP Deliverables: Natural language query over structured data. Evidence-cited answers. Verified vs discussed separation. Read-only mode first. Exit criteria: Ask Atlas can answer top governance/cost questions with evidence links. Phase 8 — Production hardening Deliverables: SSO. RBAC. Audit logs. OpenTelemetry. ClickHouse event store. Temporal workflows. Secrets manager. Kubernetes deployment. --- 11. CLI MVP 11.1 CLI name ```bash atlas ``` 11.2 Commands Health ```bash atlas status ``` Shows: API reachable. User identity. Current project. Local agent configs. Gateway config. AgentsView status. Login ```bash atlas login ``` MVP can use static token or local dev token. Production uses OIDC device flow. Project selection ```bash atlas project list atlas project use project-a ``` Writes local config: ```text ~/.config/atlas/config.toml ``` Tool registry ```bash atlas tool list atlas tool get claude-code atlas tool check claude-code --project project-a ``` Policy check ```bash atlas policy check \ --tool claude-code \ --model claude-sonnet \ --project project-a ``` Example output: ```text Decision: allow Policy version: 2026.06.15-1 Matched rules: - tool_is_official - user_group_allowed - model_allowed - project_budget_ok ``` Personal plan declaration ```bash atlas personal-plan declare atlas personal-plan list atlas personal-plan status ``` Agent bootstrap ```bash atlas agent detect atlas agent configure claude-code --project project-a atlas agent configure codex --project project-a atlas agent configure opencode --project project-a atlas agent status ``` Evidence ingest ```bash atlas evidence ingest agentsview --path ~/.agentsview atlas evidence ingest gateway --file ./sample-litellm-logs.jsonl ``` Cost ```bash atlas cost project project-a --month 2026-06 atlas cost user alice@company.com --month 2026-06 ``` 11.3 CLI MVP scope Must have: `status`. `login` dev mode. `tool list/get/check`. `project list/use`. `policy check`. `personal-plan declare`. `agent detect`. `cost project` with seed/sample data. Nice to have: Auto-config Claude Code/Codex/OpenCode. Local AgentsView status. Gateway test call. --- 12. Website MVP 12.1 Website pages Dashboard Cards: Official tools count. Experimental tools count. Prohibited tools count. Personal plans active. Monthly AI cost. Unknown/unattributed cost. Blocked policy decisions. Tool Registry Columns: Tool. Status. Runtime type. Control surface. Owner. Review date. Allowed groups. Allowed models. Tool Detail Tabs: Overview. Policy. Evidence. Cost. Integrations. Exceptions. Project Registry Columns: Project. Owner. Budget. Current spend. Cost confidence. Allowed tools. Allowed models. Project Cost Breakdown: Gateway exact cost. Provider-reported cost. AgentsView estimate. Seat allocation. Personal plan allocation. Unknown. Personal Plans Columns: User. Tool. Account email. Monthly cost. Projects. Expiry. Approval status. Migration target. Policy Decisions Columns: Timestamp. User. Tool. Project. Model. Decision. Reason. Policy version. Evidence Explorer Filters: Project. User. Tool. Agent. Model. Source. Confidence. Time range. Ask Atlas Natural language interface with evidence-based answers. 12.2 Website MVP scope Must have: Dashboard. Tool registry list/detail. Project list/detail. Personal plan list/declaration. Policy decision log. Basic cost table. Nice to have: Ask Atlas. Evidence graph visualization. Control sync status. Advanced cost charts. --- 13. Ask Atlas Ask Atlas is a read-only governance assistant over Atlas structured data and evidence. 13.1 Purpose Ask Atlas answers questions like: “Which personal plans are still active?” “Which projects used experimental tools?” “What is Project A's AI cost this month?” “Which requests were blocked because of budget?” “Show evidence that Alice used Claude Code on Project B.” “Which claims are only discussed but not verified?” 13.2 Core rule Ask Atlas must only answer from: Registry data. Evidence events. Cost records. Policy decisions. Approved external sources ingested into Atlas. It must not invent policy state. 13.3 Answer format Every answer should include: ```text Answer Confidence Evidence Caveats Next action ``` Example: ```text Project A spent $312.44 on AI in June 2026. Confidence: mixed - $220.10 verified from gateway logs - $42.34 estimated from AgentsView sessions - $50.00 allocated from Cursor personal plan reimbursement Caveat: Cursor vendor usage is not available, so Cursor personal cost is allocated, not exact. ``` 13.4 Implementation plan MVP: Text-to-SQL style constrained queries over Postgres. No write actions. No external browsing. Always cite evidence IDs. Later: RAG over evidence summaries. Graph-aware retrieval. Policy explanation assistant. Cost anomaly assistant. 13.5 Safety constraints Ask Atlas must not reveal: Raw prompts containing secrets. Sensitive source code. Customer data. Private user data beyond authorized role. Use role-based filtering before retrieval. --- 14. Main Risk 14.1 Personal plans create false governance confidence Risk: Company pays but cannot control. No central offboarding. No exact project cost. No reliable audit. Mitigation: Treat personal plans as transition/exception. Require declaration and expiry. Stop reimbursement for unregistered plans. Migrate to enterprise/team or gateway-routable tools. 14.2 Gateway cannot cover every tool Risk: Cursor/Claude/ChatGPT subscription flows may not route through gateway. Some agents do not support hooks or base URL. Mitigation: Dual-track architecture. SaaS tools governed by SSO/CASB/MDM. Coding agents governed by gateway when possible. Tools with neither become prohibited or time-bound exceptions. 14.3 Cost accuracy may be overstated Risk: Personal plans and seat-based tools do not provide project-level exact cost. Mitigation: Label cost confidence. Separate exact, provider-reported, estimated, allocated, self-reported, unknown. 14.4 Evidence contains sensitive data Risk: AgentsView/session logs may contain source code or secrets. Mitigation: Evidence retention policy. Redaction pipeline. RBAC. Default metadata-only ingestion where possible. Raw evidence access requires elevated permission. 14.5 Policy sync drift Risk: Registry says prohibited, but CASB/MDM/gateway not updated. Mitigation: Control sync status. Drift detection. Periodic reconciliation. Alert on failed sync. 14.6 Developer bypass Risk: Users install unapproved tools, use personal network, or use personal device. Mitigation: Managed device requirement. MDM/EDR inventory. CASB/SWG for managed traffic. Procurement reimbursement control. Clear acceptable use policy. 14.7 OPA/Rego complexity Risk: Policies become too complex for operators. Mitigation: Start with simple policies. Provide UI forms that generate policy inputs. Keep Rego reviewed and tested. Add policy simulation. 14.8 Tool integration churn Risk: AI tools change config format, pricing, logs, model names. Mitigation: Adapter pattern. Versioned integrations. Integration health checks. Store raw source events for reprocessing. --- 15. Research 15.1 AgentsView Key points: AgentsView is local-first session search, analytics, insights, and token usage statistics for coding agents. It supports Claude Code, Codex, Gemini CLI, OpenCode, Cursor, Pi, and many other agents. It can provide token usage and cost dashboard, per-session/per-model breakdowns, daily spend, project breakdowns. It is evidence/view layer, not enforcement layer. Research source: https://github.com/kenn-io/agentsview 15.2 Claude Code LLM Gateway Key points: Claude Code supports LLM gateway configuration. LLM gateways provide centralized authentication, usage tracking, cost controls, audit logging, model routing. Suitable for Track B gateway-routable agents. Research source: https://code.claude.com/docs/en/llm-gateway 15.3 Codex CLI custom providers Key points: Codex CLI supports custom model providers. Provider config includes `base_url` and `env_key`. Suitable for gateway-routable coding agent flow. Research source: https://developers.openai.com/codex/config-reference 15.4 OpenCode custom providers Key points: OpenCode supports OpenAI-compatible custom providers. Provider config supports `options.baseURL`, `apiKey`, and headers. Suitable for gateway-routable coding agent flow. Research source: https://opencode.ai/docs/providers/ 15.5 LiteLLM Key points: LiteLLM can run as AI Gateway / LLM Proxy. Supports multiple providers. Supports virtual keys, cost tracking, budgets, user/team/project-style management depending on edition/features. Good starting point before building a custom gateway. Research sources: https://docs.litellm.ai/docs/proxy/cost_tracking https://docs.litellm.ai/docs/proxy/virtual_keys https://github.com/BerriAI/litellm 15.6 OpenAI / ChatGPT Enterprise controls Key points: Enterprise/Business style plans provide stronger admin controls than personal plans. ChatGPT Enterprise includes centralized admin controls, domain verification, SSO, SCIM, and usage insights. Research source: https://help.openai.com/en/articles/8265053-what-is-chatgpt-enterprise 15.7 Microsoft / CASB-style AI blocking Key points: Unsanctioned AI apps can be discovered and blocked through enterprise security controls. Controls include Defender for Cloud Apps, Entra, Intune, and network controls. Unmanaged devices and personal networks remain a gap. Research source: https://learn.microsoft.com/en-us/purview/deploymentmodels/depmod-data-leak-shadow-ai-step2 15.8 OPA Key points: OPA is a general-purpose policy engine. It supports policy-as-code and can be used across microservices, Kubernetes, CI/CD, and gateways. Research source: https://openpolicyagent.org/docs 15.9 OpenTelemetry Key points: OpenTelemetry provides vendor-neutral instrumentation for traces, metrics, and logs. Useful for platform observability and auditability. Research source: https://opentelemetry.io/docs/ 15.10 ClickHouse Key points: ClickHouse is suitable for real-time analytics and high-volume event querying. Useful later for gateway logs, policy decisions, and cost events. Research source: https://clickhouse.com/use-cases/real-time-analytics --- 16. Decisions & open questions 16.1 Decisions D1 — Build new source code Atlas will be a new codebase. AgentsView remains external/evidence layer. D2 — Python backend Use Python FastAPI instead of NestJS. Rationale: Better fit for AI infra, ingestion, log processing, CLI, and LiteLLM integration. Easier for data extraction and cost processing. D3 — Docker-first development All MVP services must run with Docker Compose. D4 — OPA for policy-as-code OPA/Rego will be used for policy evaluation. D5 — LiteLLM first, custom gateway later Do not build custom gateway from scratch initially. Use LiteLLM as the gateway runtime and build Atlas adapters around it. D6 — PostgreSQL as source of truth Registry, approvals, exceptions, and core entities live in Postgres. D7 — ClickHouse later Start analytics in Postgres for MVP. Add ClickHouse when event volume requires it. D8 — Personal plans are transition/exception Company-funded personal plans are not official tools. D9 — Separate discussed vs verified Atlas must always label evidence confidence. D10 — CLI is part of MVP The CLI is necessary to support developer workflow and agent bootstrap. 16.2 Open questions Q1 — Which IdP is primary? Options: Google Workspace. Microsoft Entra ID. Okta. Need decision for OIDC/SAML integration. Q2 — Which CASB/SWG/MDM tools are available? Need current company stack: Microsoft Defender? Cloudflare Gateway? Netskope? Zscaler? Palo Alto? Intune? Jamf? Q3 — Which AI tools are currently used? Need inventory: ChatGPT personal/pro/business? Claude personal/max/team/enterprise? Cursor Pro/Business? Copilot individual/business? Claude Code? Codex CLI? OpenCode? Pi? Droid? Q4 — Can company use central provider credentials? If yes: Gateway becomes stronger. If no: Governance relies more on SaaS enterprise plans and endpoint/network controls. Q5 — What data classes are allowed in AI tools? Need company data classification: Public. Internal. Confidential. Restricted. Customer PII. Secrets. Source code categories. Q6 — How much raw evidence can be stored? Need decision: Metadata only. Redacted transcript. Full transcript with restricted access. Short retention. Long retention. Q7 — Should Atlas fork AgentsView? Initial decision: No. Open question: Later, if evidence integration requires deeper APIs, consider contributing upstream or maintaining a thin adapter. Q8 — Which model pricing source is authoritative? Options: LiteLLM model cost map. Provider pricing APIs/exports. Manually curated pricing table. Contract-specific pricing from finance. Q9 — What is the first official gateway-routable agent? Candidate: Claude Code. Codex CLI. OpenCode. Need choose one for MVP path. Q10 — What is the first enterprise SaaS AI tool to standardize? Candidate: ChatGPT Enterprise/Business. Claude Team/Enterprise. Cursor Business. GitHub Copilot Business. --- 17. Current MVP Definition 17.1 MVP objective Build a Docker-first internal AI Governance MVP that can: Register AI tools, models, projects, and personal plans. Classify tools as official/experimental/prohibited/transition_personal. Evaluate basic policy decisions with OPA. Run LiteLLM locally as AI Gateway. Ingest sample gateway logs. Ingest sample AgentsView/session evidence. Show project AI cost with confidence labels. Provide CLI for status, policy check, and personal plan declaration. Provide web UI for registry, personal plans, cost, and evidence. 17.2 MVP must-have features Registry Tool registry. Model registry. Provider registry. Project registry. User/group seed data. Personal plan declarations. Policy OPA integration. Tool allow/block policy. Model allow/block policy. Project budget check. Personal plan status check. Policy decision logs. Gateway Local LiteLLM service in Docker. Atlas-generated sample LiteLLM config. Ingest LiteLLM sample logs. Cost event creation. Evidence AgentsView sample ingestion adapter. Evidence event model. Discussed vs verified labels. Session-to-project mapping by repo path or explicit project ID. Cost Project cost table. Cost confidence labels. Gateway exact sample cost. AgentsView estimated sample cost. Personal plan allocated cost. CLI `atlas status`. `atlas tool list`. `atlas tool check`. `atlas policy check`. `atlas project use`. `atlas personal-plan declare`. `atlas cost project`. Web Dashboard. Tool registry. Project detail. Personal plans. Policy decisions. Cost explorer. Evidence explorer. 17.3 MVP out of scope Not required for first MVP: Full SSO production setup. Real CASB/MDM integrations. Full provider billing API integration. ClickHouse production pipeline. Temporal workflows. Ask Atlas write actions. Real-time blocking outside LiteLLM. Full DLP scanning. Raw transcript retention policy implementation. Neo4j/graph database. 17.4 MVP demo scenario Demo data: Users: Alice, Bob, Security Admin. Projects: Project Alpha. Project Beta. Tools: Claude Code = official. OpenCode = official. Cursor Pro Personal = transition_personal. Unknown AI Extension = prohibited. Models: claude-sonnet = official. gpt-5.4 = official. random-model = prohibited. Demo flow: Admin opens web dashboard. Admin sees Cursor Pro Personal under transition personal. Alice declares Cursor Pro personal plan. Admin approves until a date. Bob tries policy check for prohibited extension. OPA returns block. Claude Code request through sample gateway log is ingested. AgentsView sample session is ingested. Project Alpha cost page shows: ```text $120.32 total $80.00 verified gateway $20.32 estimated AgentsView $20.00 allocated personal plan ``` Evidence explorer shows the evidence records behind each number. Ask Atlas answers: ```text "Project Alpha has $80 verified gateway cost, $20.32 estimated local session cost, and $20 allocated personal plan cost. Confidence: mixed." ``` 17.5 MVP success criteria The MVP is successful if it can prove: Registry can become the source of truth. Policy decisions can be evaluated outside application code. LiteLLM can serve as the first gateway path. AgentsView can remain evidence/view layer. Personal plans can be made visible and controlled as transition state. Cost can be shown with confidence labels. Docker-first local development works. --- Appendix A — Example policy input ```json { "user": { "id": "alice@company.com", "groups": ["ai-engineering"] }, "tool": { "id": "claude-code", "status": "official", "runtime_type": "gateway_routable_agent" }, "project": { "id": "project-alpha", "status": "active", "remaining_budget_usd": 320.5 }, "model": { "id": "claude-sonnet", "status": "official" }, "data": { "classification": "internal" } } ``` Appendix B — Example policy output ```json { "decision": "allow", "reasons": [ "tool_is_official", "user_group_allowed", "project_active", "model_allowed", "budget_available" ], "policy_version": "2026.06.15-1" } ``` Appendix C — Example block output ```json { "decision": "block", "reasons": [ "tool_is_prohibited" ], "policy_version": "2026.06.15-1", "recommended_action": "Use Claude Code or OpenCode through the company AI Gateway." } ``` Appendix D — Example Makefile targets ```makefile up: docker compose up down: docker compose down migrate: docker compose exec api alembic upgrade head seed: docker compose exec api python -m atlas_api.db.seed test: docker compose exec api pytest lint: docker compose exec api ruff check . policy-test: docker compose exec opa opa test /policies ``` --- End of SPEC.md.