code-atlas-forge 1.1.0__py3-none-any.whl

code_atlas/ui/wizard.py

@@ -0,0 +1,317 @@
+"""Guided installation wizard (Experience Program §1.2).
+
+Drives the *real* install service — every choice maps to an actual
+``install()`` call; the review step is the real dry-run plan, and the
+apply step is the governed ``--yes`` path. Nothing here writes files
+itself.
+
+Flow: env check → scope → profile → execution profile → components →
+hosts → review (dry-run plan) → confirm → apply → doctor → finish.
+Each optional step is skipped when its vocabulary is empty (a forge
+with no gateway profiles, components or hosts simply never asks).
+Any step can be cancelled (Esc/q) without side effects; nothing is
+written before the explicit confirm.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from code_atlas.ui import i18n
+from code_atlas.ui.kit import (
+    NonInteractive,
+    UIContext,
+    _c,
+    confirm,
+    dashboard,
+    multi_select,
+    select,
+)
+
+_ALL_HOSTS = ("claude", "devin", "codex", "copilot")
+_SCOPES = ("project", "workspace", "user")
+_SCOPE_LABELS = {
+    "project": "Current repository",
+    "workspace": "Entire workspace",
+    "user": "My user account",
+}
+_PROFILES = ("recommended", "minimal", "full")  # service contract names
+_PROFILE_LABELS = {
+    "recommended": "Balanced (Recommended)",
+    "minimal": "Economy",
+    "full": "Full",
+}
+_GATEWAY_PROFILES = ("economy", "balanced", "deep")
+_GATEWAY_LABELS = {
+    "economy": "Economy (lowest context cost)",
+    "balanced": "Balanced (recommended)",
+    "deep": "Deep (maximum verification)",
+}
+_COMPONENTS = ("skills", "agents", "mcp", "tui", "graph-studio")
+_COMPONENT_LABELS = {
+    "skills": "Skills",
+    "agents": "Agents",
+    "mcp": "MCP",
+    "tui": "TUI",
+    "graph-studio": "Graph Studio",
+}
+_COMPONENT_DETAILS = {
+    "skills": "host-discoverable skills and progressive capability guidance",
+    "agents": "specialists, subagents and declared agent instructions",
+    "mcp": "MCP configuration and governed server entry points",
+    "tui": "the terminal command center runtime",
+    "graph-studio": "federated graph views and local graph navigation",
+}
+_COMPONENT_DEFAULTS = {
+    "minimal": {"mcp", "tui"},
+    "recommended": {"skills", "agents", "mcp", "tui", "graph-studio"},
+    "full": {"skills", "agents", "mcp", "tui", "graph-studio"},
+}
+
+
+def _has_vcs_root(start: Path) -> bool:
+    """Return whether current directory belongs to a supported project root."""
+    return any(
+        (candidate / ".git").exists()
+        or ((candidate / "forge.json").is_file() and (candidate / "pyproject.toml").is_file())
+        for candidate in (start, *start.parents)
+    )
+
+
+def _scope_choices(ctx: UIContext, scopes: tuple[str, ...]) -> list[str]:
+    """Hide repository-only choice when operator is in a fresh directory."""
+    choices = list(scopes)
+    if "project" in choices and not _has_vcs_root(Path.cwd()):
+        print(
+            _c(
+                ctx,
+                "33",
+                "  No repository detected; choose Entire workspace to use this directory "
+                "or My user account.",
+            )
+        )
+        choices.remove("project")
+    return choices
+
+
+def env_check_rows(hosts: tuple[str, ...] = _ALL_HOSTS) -> list[tuple[str, str]]:
+    """Real environment evidence: python, git, host binaries."""
+    v = sys.version_info
+    rows = [("Python", f"{v.major}.{v.minor}.{v.micro}")]
+    rows.append(("Git", "OK" if shutil.which("git") else "missing"))
+    for h in hosts:
+        rows.append((h.capitalize(), "Available" if shutil.which(h) else "not detected"))
+    return rows
+
+
+def _banner(ctx: UIContext, forge_name: str) -> None:
+    print()
+    print(_c(ctx, "1", f" {forge_name.upper()}"))
+    print(_c(ctx, "2", " " + ("─" if ctx.unicode else "-") * max(10, len(forge_name) + 4)))
+    print(f"  {i18n.t('env_detected', ctx.language)}:")
+
+
+def run_wizard(
+    *,
+    forge_name: str,
+    install_fn: Any,
+    doctor_fn: Any | None = None,
+    hosts_available: tuple[str, ...] = _ALL_HOSTS,
+    gateway_profiles: tuple[str, ...] = _GATEWAY_PROFILES,
+    scopes: tuple[str, ...] = _SCOPES,
+    component_order: tuple[str, ...] | None = _COMPONENTS,
+    component_labels: dict[str, str] | None = None,
+    component_details: dict[str, str] | None = None,
+    component_defaults: dict[str, set[str]] | None = None,
+    env_hosts: tuple[str, ...] | None = None,
+    next_hint: str | None = None,
+    ctx: UIContext | None = None,
+    out_json: bool = False,
+    family: bool = False,
+) -> int:
+    """Interactive install wizard. Returns exit code.
+
+    ``install_fn(**kwargs)`` is the forge's real install service
+    (``host``/``scope``/``profile``/``gateway_profile``/``components``/
+    ``dry_run``/``yes`` kwargs). ``doctor_fn`` optionally verifies
+    post-install. Empty vocabularies skip their step: no hosts, no
+    gateway profile or no components means the question is never asked.
+    """
+    ctx = ctx or UIContext.detect()
+    if not ctx.interactive:
+        raise NonInteractive("install wizard requires a TTY")
+
+    comp_order = component_order or ()
+    comp_labels = component_labels or _COMPONENT_LABELS
+    comp_details = component_details or _COMPONENT_DETAILS
+    comp_defaults = component_defaults or _COMPONENT_DEFAULTS
+
+    _banner(ctx, forge_name)
+    env_rows = env_check_rows(hosts_available if env_hosts is None else env_hosts)
+    for label, val in env_rows:
+        print(f"    {label:<14} {_c(ctx, '32' if val in ('OK', 'Available') else '2', val)}")
+    print()
+    if family:
+        print(_c(ctx, "36", "  family mode: The Forge + registered specialist forges"))
+        print(_c(ctx, "2", "  one real plan, one approval, each forge keeps its own installer"))
+        print()
+
+    # --- scope ---------------------------------------------------------------
+    scope_choices = _scope_choices(ctx, scopes)
+    idx = select(
+        i18n.t("install_scope_q", ctx.language),
+        [_SCOPE_LABELS.get(s, s) for s in scope_choices],
+        ctx=ctx,
+    )
+    if idx is None:
+        return 130
+    scope = scope_choices[idx]
+
+    # --- profile -------------------------------------------------------------
+    idx = select(
+        i18n.t("install_profile_q", ctx.language),
+        [_PROFILE_LABELS[p] for p in _PROFILES],
+        ctx=ctx,
+    )
+    if idx is None:
+        return 130
+    profile = _PROFILES[idx]
+
+    # --- execution profile ----------------------------------------------------
+    gateway_profile: str | None = None
+    if gateway_profiles:
+        idx = select(
+            i18n.t("install_gateway_profile_q", ctx.language),
+            [_GATEWAY_LABELS.get(p, p) for p in gateway_profiles],
+            ctx=ctx,
+        )
+        if idx is None:
+            return 130
+        gateway_profile = gateway_profiles[idx]
+
+    # --- optional components ---------------------------------------------------
+    components: tuple[str, ...] | None = None
+    if comp_order:
+        comp_checked = comp_defaults.get(profile, set())
+        print(_c(ctx, "2", "  component choices (economy loads optional knowledge/evals on demand):"))
+        for component in comp_order:
+            detail = comp_details.get(component)
+            print(f"    {component:<13} {detail}" if detail else f"    {component}")
+        comp_chosen = multi_select(
+            i18n.t("install_components_q", ctx.language),
+            [comp_labels.get(c, c) for c in comp_order],
+            checked={i for i, c in enumerate(comp_order) if c in comp_checked},
+            ctx=ctx,
+        )
+        if comp_chosen is None:
+            return 130
+        components = tuple(sorted(comp_order[i] for i in comp_chosen))
+
+    # --- hosts ---------------------------------------------------------------
+    host_arg: str | None = None
+    if hosts_available:
+        detected = {
+            i
+            for i, h in enumerate(hosts_available)
+            if any(h in r[0].lower() and r[1] == "Available" for r in env_rows)
+        }
+        chosen = multi_select(
+            i18n.t("install_hosts_q", ctx.language),
+            list(hosts_available),
+            checked=detected,
+            ctx=ctx,
+        )
+        if chosen is None:
+            return 130
+        if not chosen:
+            host_arg = None
+        elif len(chosen) == len(hosts_available):
+            host_arg = "all"
+        else:
+            host_arg = ",".join(hosts_available[i] for i in sorted(chosen))
+
+    # --- review (real dry-run plan) ------------------------------------------
+    # Contrato explícito: install_fn aceita `components` — wrappers **kw
+    # encaminham sem inspeção de assinatura (GAP-002).
+    kwargs: dict[str, Any] = {
+        "scope": scope,
+        "profile": profile,
+        "gateway_profile": gateway_profile,
+        "components": components,
+    }
+    try:
+        # `none` é opt-out explícito — zero hosts escolhidos nunca vira
+        # "all" (GAP-003); csv de subconjunto é contrato válido (GAP-003b).
+        plan = install_fn(host=host_arg or "none", dry_run=True, **kwargs)
+    except Exception as exc:
+        print(_c(ctx, "31", f"plan failed: {exc}"))
+        return 1
+
+    planned = (
+        plan.get("planned")
+        or plan.get("planned_files")
+        or plan.get("writes")
+        or plan.get("plan")
+        or []
+    )
+    review_rows = [
+        ("scope", scope),
+        ("profile", profile),
+    ]
+    if gateway_profile is not None:
+        review_rows.append(("execution", gateway_profile))
+    review_rows.append(("mode", "family" if family else "this forge"))
+    if comp_order:
+        review_rows.append(("components", ", ".join(components or ()) or "none"))
+    if hosts_available:
+        review_rows.append(("hosts", host_arg or "none"))
+    review_rows.append(
+        ("managed writes", str(len(planned) if isinstance(planned, list) else planned))
+    )
+    dashboard(
+        f"{forge_name} — {i18n.t('review', ctx.language)}",
+        [("Plan", review_rows)],
+        ctx=ctx,
+    )
+    if isinstance(planned, list):
+        for entry in planned[:10]:
+            if isinstance(entry, dict):
+                path = str(entry.get("path") or entry.get("target") or "")
+            else:
+                path = str(entry)
+            print(f"    {_c(ctx, '2', path)}")
+        if len(planned) > 10:
+            print(f"    … {len(planned) - 10} more")
+
+    if not confirm(i18n.t("confirm_q", ctx.language), default=True, ctx=ctx):
+        return 130
+
+    # --- apply (real governed install) ---------------------------------------
+    receipt = install_fn(host=host_arg or "none", yes=True, dry_run=False, **kwargs)
+    status = receipt.get("status", "unknown")
+    if out_json:
+        print(json.dumps(receipt, indent=2, ensure_ascii=False))
+    color = "32" if status == "completed" else "31"
+    print(f"\n  {i18n.t('status', ctx.language)}: {_c(ctx, color, status)}")
+
+    # --- verify --------------------------------------------------------------
+    if doctor_fn is not None and status == "completed":
+        health = doctor_fn(scope=scope)
+        raw_health = health.get("status") or health.get("health") or "unknown"
+        hstatus = raw_health
+        if isinstance(raw_health, dict):
+            hstatus = raw_health.get("status", "unknown")
+        color = "32" if hstatus in ("healthy", "PASS") else "33"
+        print(f"  {i18n.t('health', ctx.language)}: {_c(ctx, color, str(hstatus))}")
+
+    if status == "completed" and next_hint:
+        print(f"  next: {next_hint}")
+
+    return 0 if status == "completed" else 1
+
+
+__all__ = ["run_wizard", "env_check_rows", "NonInteractive", "UIContext"]

code_atlas_forge-1.1.0.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: code-atlas-forge
+Version: 1.1.0
+Summary: Plataforma local-first de inteligência estrutural de código — Cycle 4.1: retrieval, context packs, MCP e evidência canônica
+Author: Edgar Socrates
+License-Expression: Apache-2.0
+Keywords: code-intelligence,code-graph,static-analysis,local-first
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: tree-sitter==0.25.2
+Requires-Dist: tree-sitter-python==0.23.6
+Requires-Dist: tree-sitter-typescript==0.23.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.11.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mcp>=2.3.0; extra == "dev"
+Provides-Extra: vector
+Requires-Dist: sqlite-vec>=0.1.6; extra == "vector"
+Dynamic: license-file
+
+# Code Atlas Forge
+
+<p align="center">
+  <img src="docs/assets/logo.png" alt="Code Atlas logo" width="420" />
+</p>
+
+Plataforma **open source, local-first e offline-first** de inteligência estrutural,
+semântica e arquitetural de software — grafos tipados, proveniência verificável,
+indexação incremental e contexto econômico para agentes.
+
+> **Status atual: Cycle 8 — production quality em andamento
+> (branch `cycle-8-production-quality`); Cycle 7 (inteligência de
+> domínio + federação) entregue e arquivado.**
+> O Code Atlas indexa repositórios com parsing real (Tree-sitter), extrai
+> símbolos e constrói um grafo tipado persistido em SQLite, consultável via
+> CLI, servidor MCP stdio, **API HTTP loopback `/api/v1`** e o
+> **Explorer** — workbench visual Angular servido por
+> `code-atlas explorer`. Análise de impacto entre revisões
+> (`code-atlas impact` / `POST /impact/analyze`) está disponível com
+> estados de binding honestos. O Cycle 7 adiciona **seis adapters de
+> domínio opt-in** (SQL, PySpark, AWS data, API contracts, Terraform,
+> CI/CD) com grafo de domínio snapshot-scoped (schema v9), **resolução
+> cross-domain** por identidade qualificada, **federação multi-repo**
+> read-only com pins por snapshot (schema v10), faceta de domínio e
+> busca federada no SearchEngine, blast radius misto no Impact Engine,
+> context packs de domínio, cinco telas novas no Explorer e layout FA2
+> assíncrono em Web Worker (RAF gap máx. 83 ms, era ~2300 ms). Veja
+> `docs/cycle-7-architecture.md`, `docs/cycle-7-homologation.md`,
+> `docs/cycle-7-limitations.md` e `docs/roadmap.md`.
+
+## Princípios
+
+- **Local-first:** nenhum serviço externo, Docker, conta SaaS ou API key é
+  necessário para operar. Nenhum dado sai da máquina por padrão.
+- **Sem telemetria:** não existe código de telemetria no projeto — a coleta
+  não é apenas desligada por padrão, ela está ausente.
+- **O repositório indexado é não confiável:** nada do código varrido é
+  executado, importado ou instalado.
+- **Evidência primeiro:** toda relação carrega origem, extrator, versão,
+  confiança e status de resolução.
+- **Determinismo:** a mesma árvore produz o mesmo grafo e os mesmos ids.
+
+A especificação arquitetural normativa está em `docs/BLUEPRINT-v1.md`.
+
+## Instalação
+
+Requer Python 3.12+. Dependências de runtime pinned: `tree-sitter` +
+gramáticas (ADR-015) — instaladas automaticamente via wheels.
+
+```bash
+git clone https://github.com/EdgarSocrates98/code-atlas-forge.git
+cd code-atlas-forge
+python3 -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install .
+code-atlas --version
+code-atlas doctor
+```
+
+Para desenvolvimento: `pip install -e .[dev]`.
+Detalhes em `docs/install.md`.
+
+## Uso rápido
+
+```bash
+code-atlas init --root /caminho/do/repo   # configura o workspace (XDG/APPDATA)
+code-atlas doctor                        # verifica ambiente e config
+code-atlas index /caminho/do/repo        # incremental é o default; --full força rebuild
+code-atlas index . --scip idx.scip       # binding SCIP ad-hoc (proveniência mantida)
+code-atlas index . --resolver scip       # restringe resolvers ativos (erro tipado se desconhecido)
+code-atlas index-plan /caminho/do/repo   # dry-run do IndexPlan, sem tocar no DB
+code-atlas status --json                 # estado do índice, git, migrações
+code-atlas semantic-status . --json      # resolvers: installed/enabled/used + coverage do READY
+
+# consultas sobre o snapshot READY (envelope v2)
+code-atlas search "Engine" --json        # substring em qualified_name
+code-atlas symbol pkg.core.Engine        # detalhe + ocorrências
+code-atlas references pkg.util.helper    # incoming, com status/confiança
+code-atlas definitions pkg.util.helper   # defs + declarações do símbolo
+code-atlas dependencies pkg.app.main --depth 2   # BFS outgoing, cycle-safe
+code-atlas graph --json                  # dump de nós+arestas do snapshot
+
+# retrieval híbrido + contexto (Cycle 4)
+code-atlas search "q" --strategy lexical|structural|graph|hybrid --limit 10 --json
+code-atlas context "create_order" --level focus --budget 4000 --format markdown
+code-atlas context-expand --symbol pkg.orders.validate_total --snapshot 1 --delivered sym:pkg.orders
+code-atlas mcp                            # servidor MCP stdio (JSON-RPC ndjson)
+code-atlas mcp doctor --json              # executável, DB, schema, sqlite_vec
+code-atlas mcp manifest --host claude-code   # emite config (nunca escreve)
+
+# impacto entre revisões/snapshots (Cycle 5)
+code-atlas impact report --base HEAD~1 --target HEAD --format json
+
+# API local + Explorer visual (Cycle 6)
+code-atlas api --port 8741                # só /api/v1, loopback, read-only
+code-atlas explorer --open                # API + UI Angular compilada
+
+# domínios + federação (Cycle 7 — opt-in, default OFF)
+code-atlas index . --domains sql,pyspark --cross-domain   # extrai domínio no snapshot
+code-atlas domains list                    # adapters registrados (listar não extrai)
+code-atlas domains entities --domain sql   # entidades do snapshot READY
+code-atlas domains entity 'sql:mart.daily_revenue'
+code-atlas domains lineage staging.orders --direction up --depth 3
+code-atlas federation create minha-view    # workspace multi-repo
+code-atlas federation add minha-view /repo/a
+code-atlas federation add minha-view /repo/b
+code-atlas federation pin minha-view a 42  # pin de snapshot (latest desfaz)
+code-atlas federation view minha-view --json
+```
+
+Filtros: `--language`, `--kind`, `--path`, `--snapshot`,
+`--relation-type`, `--limit`/`--offset`. Saída JSON estável com
+`schema_version`. Detalhes: `docs/structural-search.md`, `docs/hybrid-search.md`,
+`docs/graph-retrieval.md`, `docs/context-engineering.md`,
+`docs/mcp-server.md`.
+
+Configuração: `--root` > variáveis `CODE_ATLAS_*` > `XDG_CONFIG_HOME` /
+`%APPDATA%`. Nada é escrito dentro do repositório indexado.
+
+## Linguagens suportadas (Cycle 2)
+
+Python (`.py`/`.pyi`), TypeScript (`.ts` variantes), TSX (`.tsx`) —
+matriz completa com versões de gramática pinned em
+`docs/parser-adapters.md`. Arquivos de outras linguagens entram no
+inventário como nós `file`, sem extração.
+
+## Limitações
+
+Implementado hoje: parsing sintático real, símbolos/referências/
+relações com proveniência por aresta, resolução syntactic **integrada**
+a resolvers opt-in SCIP/LSP, indexação incremental com cache
+versionado, snapshots atômicos, busca estrutural SQL, **FTS5
+snapshot-scoped**, **retrieval híbrido (RRF k=60 + rerank task-aware
+opt-in)**, graph retrieval multi-seed com direção por intent,
+**context packs** com budget do payload serializado e expansão
+progressiva, **servidor MCP stdio** (read-only, homologado com o SDK
+oficial `mcp`), **impact engine** entre revisões/snapshots com binding
+honesto (`partial`/`mismatch`/`unavailable` nunca viram resultado
+verificado), **API HTTP loopback `/api/v1`** stdlib read-only
+(ADR-0009), o **Explorer Angular** (`code-atlas explorer`) — grafo
+bounded, busca, impacto, revisões, context packs e diagnósticos — e,
+no Cycle 7, **adapters de domínio opt-in** (SQL/PySpark/AWS data/
+API/Terraform/CI-CD, stdlib-only, zero deps novas), **grafo de
+domínio** persistido com estados `resolved`/`ambiguous`/`unresolved`/
+`external`, **resolução cross-domain** por identidade qualificada,
+**federação multi-repo** com snapshot pinado por membro, **busca
+federada** e faceta `domain`, **blast misto** símbolo+domínio,
+**context packs de domínio** e **views de domínio no Explorer**
+(`/lineage`, `/contracts`, `/infra`, `/pipelines`, `/federation`).
+
+**Não implementado** (por design): type-checking real (resolver
+sintático não infere receiver — `d.speak()` fica `unresolved`),
+embeddings semânticos reais (provider naïve documentado, ADR-0022),
+structural sharing de grafo entre snapshots (rejeitado, ADR-0020),
+escrita via API/UI (read-only por contrato), telemetria (ausente por
+spec), conexão com cloud real (adapters de domínio leem só artefatos
+declarados no repo — zero rede, zero execução), mutação de federação
+por HTTP (CLI-only), FTS de entidades de domínio (`q=` é `LIKE`).
+
+**Homologado com ressalvas** (Cycle 6.1 — `docs/cycle-6.1-limitations.md`):
+sem benchmark de 10k nós (máximo medido: 2000 renderizados; API trunca a
+2000, canvas capa a 500/2000), arestas do overview sem custo medido
+(0 edges por design), Firefox/Safari/Windows interativo **NOT RUN**,
+sem passeio com screen reader, ~55 vulnerabilidades `npm audit` (0
+critical em produção — `docs/cycle-6.1-dependency-audit.md`).
+**Verificado no 6.1:** 102 testes Playwright (flows, security, a11y,
+scale, screenshots) verdes no job `explorer-e2e`; auditoria axe WCAG 2.2
+AA em 24 scans com **0 violações**; rate limit 300/min + timeout 30 s +
+CSP/XFO na API; drill-down via `GET /files/{id}/occurrences`;
+`evidence_ids` emitidos nas arestas; canvas congelado pós-relayout
+corrigido e medido; `npm ci` reproduzível.
+Estados `unresolved`/`ambiguous`/`external` são preservados como
+fatos — nunca preenchidos por heurística. Detalhes:
+`docs/semantic-resolution.md`, `docs/cycle-3.1-evidence.md`,
+`docs/semantic-accuracy-report.md`, `docs/cycle-6-homologation.md`,
+`docs/cycle-6.1-evidence.md`, `docs/cycle-7-homologation.md`,
+`docs/cycle-7-limitations.md`.
+
+## Estrutura do repositório
+
+```
+src/code_atlas/     pacote (layout src; deps pinned = tree-sitter)
+  contracts/        modelos de domínio, enums, ports (hexagonal)
+  discovery/        scanner Git-aware + manifest de inventário
+  parsers/          engine + registry + adaptadores tree-sitter
+  graph/            builder canônico, identidades, validação
+  resolvers/        syntactic + SCIP/LSP opt-in, enrichment, bootstrap
+  storage/          SQLite: migrações v1-v10, snapshots, FTS5
+  indexing/         coordinator + persistência do grafo
+  search/           StructuralSearch (SQL parametrizado)
+  impact/           ImpactEngine: diff, binding, blast misto, risco, testes
+  domains/          adapters de domínio opt-in (sql, pyspark, aws, api,
+                    terraform, cicd) + registry, identity, crossresolve
+  federation/       workspaces multi-repo, pins, views (schema v10)
+  eval/             suporte do runner de avaliação por goldens
+  api/              HTTP loopback read-only /api/v1 (stdlib, ADR-0009)
+  observability/    logging estruturado + redaction (sem telemetria)
+explorer/           workbench Angular 18 (SPA servida por `code-atlas explorer`)
+tests/              suíte pytest (unitários, golden corpus, e2e, bench)
+docs/               blueprint, ADRs, roadmap, schemas, evidências
+factory/            specs Loop Factory (inbox/active/archive + audit)
+benchmarks/         bench_scan (cycle-1) + bench_index (cycle-2)
+```
+
+## Desenvolvimento
+
+```bash
+pip install -e .[dev]
+ruff check src tests && mypy src && pytest -q
+```
+
+## Licença
+
+Apache-2.0 — veja `LICENSE` e `NOTICE`.