forgeos 0.1.0-alpha.68 → 0.1.0-alpha.69

package/.agents/skills/forge-agent-fabric/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: forge-agent-fabric
-description: Conduct or resume a Forge Agent Fabric coding task with persistent workflow steps, independent Codex review, and source-bound evidence when the user requests this workflow.
+description: Conduct or resume Forge Agent Fabric tasks and prepare repository manifests, analysis maps and source-bound context in existing projects, including Vue, Java and Docker.
 ---
 
 # Forge Agent Fabric
@@ -38,6 +38,26 @@ Native MCP tools are `fabric_attached_*`, `fabric_workflow_*` and `fabric_run_*`
 offers the same operations. State which transport you actually demonstrated.
 Do not register MCP or change global configuration as a side effect of using this skill.
 
+## Analyze an existing repository
+
+When asked to prepare a project for Forge maps, read
+[repository analysis](references/repository-analysis.md). Use the shared runtime through
+`scripts/repository.mjs --project <target-directory> manifest|repository|cair <operation>`.
+This helper does not require Git; managed Fabric execution still requires Git with HEAD.
+Discovery returns a proposal. Inspect it against project instructions and code, then prepare
+`forge.manifest.json` only when edits are authorized. Preserve an existing service manifest.
+Validate the repository manifest before analyzing. Maps describe static evidence and
+coverage gaps, not runtime availability or executed test coverage. Checks are suggestions;
+never execute them just because the manifesto contains them. Do not start containers,
+build Java, execute configuration scripts or install hooks/MCP during static analysis.
+Use repository queries to give each task compact context with snapshotId. Refresh analysis
+when sources change, and never reuse source snippets or handles from a stale snapshot.
+For manifests stored outside the project, keep passing the same explicit `--manifest`
+to analysis and CAIR queries; the helper binds their root from `--project`.
+Managed SDK workers receive analysis from their own prepared clone when it contains a
+valid repository manifest. This context supplements acceptance checks and does not
+change publication or review requirements.
+
 Read [managed request fields and examples](references/managed-workflows.md) before
 preparing run-start. The references travel with this skill and require no Forge checkout.
 For MCP, inspect tool schemas and select the registered target project explicitly through

package/.agents/skills/forge-agent-fabric/references/repository-analysis.md

@@ -0,0 +1,102 @@
+# Repository manifests and maps
+
+Use Forge as analysis tooling in an existing project without adding the Forge application
+runtime. Shared installation is enough. Vue/Nuxt, Java/Spring, TypeScript/JavaScript and
+Docker/Compose adapters report their coverage; partial static knowledge remains partial.
+
+Run these with the absolute installed skill helper and an explicit target directory:
+
+```text
+node <skill>/scripts/repository.mjs --project <project> manifest discover --json
+node <skill>/scripts/repository.mjs --project <project> manifest validate forge.manifest.json --json
+node <skill>/scripts/repository.mjs --project <project> repository analyze --write --json
+node <skill>/scripts/repository.mjs --project <project> repository context --query routes --json
+node <skill>/scripts/repository.mjs --project <project> repository context --query coverage --json
+node <skill>/scripts/repository.mjs --project <project> repository quality --cases <absolute-reviewed-cases.json> --json
+node <skill>/scripts/repository.mjs --project <project> cair query "Q S name=<symbol>" --snapshot-id <snapshot-id> --json
+```
+
+Discovery is read-only by default: it returns a draft for the agent to review and save within the
+user's authorized scope. Confirm component roots and adapters against actual files,
+retain uncertainty, and do not overwrite a service 1.0 manifest. Repository manifests
+use `forgeProtocol: "2.0"` and `kind: "repository"`. Keep paths relative to the project.
+The manifest configures analysis; it is not a hand-maintained symbol inventory.
+
+Validate before analyzing. Analysis with `--write` saves explicit output to `.forge/repository/`
+unless a host-local cache destination is requested. Without `--write`, analysis returns
+an ephemeral snapshot and creates no cache. It does not alter
+generated application code, `.gitignore`, application dependencies or global integrations.
+Use `--help` for supported flags and current query grammar. Query results identify the
+snapshot and source evidence; a stale-source diagnostic requires fresh analysis.
+
+The helper binds `--project` explicitly for repository operations and CAIR. For a manifest
+kept outside the project, add `--manifest <absolute-file>` consistently to analysis and
+queries. Its location does not redefine the project root. Do not substitute another
+project's snapshot or leave out the external manifest when querying that snapshot.
+
+Do not read actual `.env` or secret files to resolve infrastructure. Unknown interpolation,
+dynamic URLs, Java reflection, Vue dynamic components and unresolved imports are gaps,
+not permission to infer certainty. A Compose dependency is declared topology, not observed
+traffic. A statically associated test is not proof that it ran or covered the component.
+
+For Fabric, keep analysis configuration in the project before run-start. Each SDK attempt
+analyzes its prepared clone after upstream changes and environment preparation. Clone
+snapshot IDs cannot be substituted with the original checkout's snapshot. Maps do not
+remove required reviews/checks, execute suggested checks, or authorize publication.
+Worker packets prioritize task matches and scoped symbols, include both endpoints of
+every returned edge, and declare truncation when their context budget omits facts.
+Their phase is `prepared-input`, not an assertion about later worker edits. Invalid
+configuration yields unavailable maps without echoing manifest source values in run status.
+
+Use optional `component.analysis.aliases` and `component.analysis.nuxt` to declare
+contained local resolution paths that executable config cannot establish statically.
+These paths are relative to the component root. `httpClients` may map a client ID
+(including `$api`) and file scope to a literal base path/API component. Record the
+scenario behind a mapping: a deployment default is declared evidence and never
+observed routing. Keep unknown URLs and ambiguous endpoints unresolved.
+
+Task context prioritizes exact/scoped targets, relevant consumers and case-level
+test evidence. A test-file import does not associate all sibling cases with that
+function. Included neighbors outside write scope are read-only. Suggested checks
+retain argv arrays, working directories, selection reasons, cost/category and
+unknown/missing/satisfied symbolic requirements; no check runs during map preparation.
+`ready` means the packet was prepared. Static quality is always partial and does not
+claim runtime observation.
+
+For quality review, prepare a JSON task array with `id`, `query`, `expectedFiles`
+and optionally `scope`, `expectedTests`, `forbiddenFiles` and `forbiddenTests`.
+Run `repository quality` against a current explicitly saved snapshot. It returns
+missing/forbidden associations, context size, truncation and recall/precision against
+the supplied expected file set. Require a reviewed set; do not remove failing
+expectations merely to obtain a pass. This read-only benchmark runs no models or
+application tests and cannot establish productivity improvement or executed coverage.
+
+Large v2 caches use hash-checked partitions and on-demand hydration, with complete
+integrity validation and a two-partition decoded cache. V1 compatibility is eager;
+wide queries may retain extra results. Analysis with --write maintains orphan caches
+after conservative retention; cache-gc defaults to preview and --write applies it.
+Never reclaim a foreign lock or treat serialized resident bytes as heap usage.
+Use benchmark-plan with reviewed cases and explicit model settings to prepare a paired
+experiment; benchmark-report evaluates supplied evidence without running workers/checks.
+Missing evidence is unknown, and model execution still requires authorized cost/scope.
+Matching parse facts can be reused read-only in a managed clone, but its graph,
+root, manifest/scenario connections and freshness are rebuilt. No per-project
+dependency, native hook or MCP installation is required for this flow. These features
+require a runtime containing the quality implementation; copying a newer skill onto
+an older runtime does not upgrade that runtime.
+
+Runtime observations are optional and explicit. Add reviewed `runtime.observations`
+with commands, contained cwd and generated artifact paths, then use `repository
+runtime-plan --environment-id local --json` before `runtime-observe --environment-id
+local --execute --write --json`. The latter executes trusted argv in an independent
+temporary source copy; it is not an OS/network/container security sandbox. Dependencies
+must be prepared by declared commands. Do not copy credentials or assume external
+services are authorized merely because a manifest mentions them. No model runs here.
+`runtime-context` reads sanitized bounded evidence, validates input bindings and expiry,
+and never executes. Nuxt registrations, Spring exports, Docker inspection and HTTP
+traces retain their format-specific limitations; they are not exhaustive runtime coverage.
+Exporters must close external resources they start. No hook or MCP installation is needed
+per project. Fabric can add matching saved observations to a prepared worker packet
+without running an exporter; composed input changes invalidate this reuse. Keep original
+protected repositories read-only and use the dedicated pilot copies for validation.
+See `docs/repository-runtime-observation.md` for the contract and execution examples.

package/.agents/skills/forge-agent-fabric/scripts/repository.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync, existsSync, statSync } from 'node:fs';
+import { dirname, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+// Analysis can target a directory without Git. Runtime configuration never sets cwd.
+const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+try {
+  const args = process.argv.slice(2);
+  let project = process.cwd();
+  if (args.filter(arg => arg === '--project').length > 1) throw new Error('--project may be supplied only once');
+  const index = args.indexOf('--project');
+  if (index >= 0) {
+    if (!args[index + 1] || args[index + 1].startsWith('--')) throw new Error('--project requires a target directory');
+    project = args[index + 1];
+    args.splice(index, 2);
+  }
+  const cwd = realpathSync(project);
+  if (!statSync(cwd).isDirectory()) throw new Error('Analysis project must be a directory');
+  const surface = args.shift();
+  if (!['manifest', 'repository', 'cair'].includes(surface)) throw new Error('Choose manifest, repository or cair before the operation');
+  if (index >= 0 && (surface === 'repository' || surface === 'cair' || (surface === 'manifest' && args[0] === 'discover')) && !args.includes('--root')) args.push('--root', cwd);
+  let runtime = {};
+  const config = resolve(skillRoot, 'runtime.json');
+  if (existsSync(config)) runtime = JSON.parse(readFileSync(config, 'utf8'));
+  let cliPath = process.env.FORGE_FABRIC_CLI || runtime.cliPath;
+  if (!cliPath) {
+    const lookup = spawnSync(process.platform === 'win32' ? 'where.exe' : 'which', ['forge'], { encoding: 'utf8', windowsHide: true });
+    for (const candidate of lookup.stdout?.trim().split(/\r?\n/).filter(Boolean) || []) {
+      const bin = realpathSync(candidate);
+      cliPath = [bin, resolve(dirname(bin), 'node_modules/forgeos/bin/forge.mjs')].find(path => path.endsWith('.mjs') && existsSync(path));
+      if (cliPath) break;
+    }
+  }
+  if (!cliPath || !isAbsolute(cliPath) || !existsSync(cliPath)) throw new Error('Forge runtime not found. Install this skill with --runtime <absolute forge.mjs>, or set FORGE_FABRIC_CLI.');
+  // No recorder Delta side effects for repository reads; artifacts are explicit analyze outputs.
+  const result = spawnSync(runtime.nodeExecutable || process.execPath, [realpathSync(cliPath), surface, ...args, '--no-delta'], { cwd, stdio: 'inherit', windowsHide: true });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.68 input=eb85ce79777e8854119a312edd29262099578bdd5f8be82c03b5f0caae80f391 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
+// @forge-generated generator=0.1.0-alpha.69 input=a62f6d9631d76e83840b1f77cac5b6c6e1f6da1acab63d41614e2fe47b9d5ca7 content=721818a6f9a664aa898092d4aa5cd68cbbd8ad6e150c7d3ad3ef785a2e3fcf53
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # forgeos
 
+## Unreleased
+
+- Add opt-in repository runtime observation with independent temporary source copies, bounded Nuxt/Spring/Docker/HTTP artifact collectors, input-bound expiring reports and shared CLI/MCP plan/observe/context operations. Fabric consumes only compatible saved observations, without implicit project execution.
+- Recover once from a premature Bun/Windows process-identity timeout while retaining unknown identity on repeated failures; protect existing lock ownership semantics.
+
+- Complete large-map query storage with lazy hydration and streaming fingerprints; preserve legacy caches, cap resident partitions and avoid relation-ranking read amplification. Maintain retained orphan chunks automatically and expose cache-gc previews. Add source-bound paired agent benchmark planning/reporting without implicit model execution.
+
+- Improve repository task context with deterministic scoped retrieval, case-level test associations, local Nuxt resolution and explicit HTTP client mappings. Expose static quality and informative check requirements without executing project commands.
+- Store large maps and root-neutral parse facts in validated partitions, reuse matching facts in prepared Fabric clones, and add a read-only `repository quality --cases` benchmark for reviewed expectations.
+
+## 0.1.0-alpha.69
+
+### Patch Changes
+
+- Add repository manifests and static Vue, Java, and Docker maps for existing projects, with snapshot-bound CAIR queries and clone-specific Agent Fabric context. Preserve service manifests and keep discovery, validation, and context reads free of implicit project execution or local recorder writes.
+
 ## 0.1.0-alpha.68
 
 ### Patch Changes

package/README.md

@@ -140,9 +140,18 @@ npm run field:test -- --package-managers npm --templates minimal-web --forge-spe
 
 The scheduled/manual `Field Tests` workflow expands that coverage across Linux, macOS, Windows, Node 22, Node 24, and npm/pnpm/yarn/bun.
 
-## External Runtimes And Adapters
-
-ForgeOS can import services written outside TypeScript through the Forge Protocol.
+## External Runtimes And Adapters
+
+For agent maps in an existing Vue, Java/Spring, TypeScript, or Docker/Compose repository,
+use the shared CLI without migrating the app to Forge. `forge manifest discover --json`
+proposes a repository manifest; after reviewing and saving it, run
+`forge repository analyze --write --json` and `forge repository context --query routes --json`.
+The same maps are available through CAIR and feed prepared Agent Fabric clones.
+Discovery and queries do not start project tools; maps report static coverage and unresolved relations.
+See [Repository Analysis](docs/repository-analysis.md) for the versioned manifest,
+host-local cache options, snapshot-bound queries and language limitations.
+
+ForgeOS can import services written outside TypeScript through the Forge Protocol.
 External runtimes publish a `forge.manifest.json` that describes commands, queries,
 transport, policies, risk metadata, tenant scope, and schemas. Forge then emits
 the same machine-readable app/API/agent artifacts and exposes runtime bridge

package/docs/agent-fabric.md

@@ -1,5 +1,10 @@
 # Forge Agent Fabric
 
+Existing repositories can attach optional [runtime observations](repository-runtime-observation.md)
+to their maps. Worker preparation reads compatible saved evidence without executing
+exporters; changes composed into a clone invalidate reuse. A runtime observation does
+not satisfy verification gates or extend worker write scope.
+
 Forge Agent Fabric is an experimental protocol-oriented execution layer for dynamically materialized agents and workflows. It extends Forge's existing compiler, outbox, actions, workflows, policy, and agent runtime rather than replacing them.
 
 ## Implementation status
@@ -58,6 +63,14 @@ through a mutable folder. The optional environment object accepts mode auto/none
 ignoreScripts, timeoutMs (100..1800000) and an HTTPS registry without credentials, query
 or fragment. Reviewers and commands are read-only after environment preparation.
 
+Tracked assets larger than 16 MiB outside the task's editable and captured configuration
+scope remain in Git clones as read-only inputs. Inventories record their SHA-256 by
+streaming 256 KiB blocks, without embedding asset bytes in worker metadata. Fingerprints
+include asset sizes; baseline and out-of-scope changes are still rejected. These assets
+are bounded to 512 MiB each and 1 GiB in aggregate. Editable snapshots retain their
+16 MiB per-file / 128 MiB aggregate limits, and changed artifacts retain the 8 MiB
+per-file limit. Declaring a large asset as editable does not bypass those bounds.
+
 Controls are run-steer/pause/resume/cancel/reconcile. Mutations require
 `{runId,requestId,expectedVersion}` and complete `--file` bodies. Reuse requestId only for
 the identical body; after a version conflict read status and choose a new requestId.

package/docs/architecture/agent-fabric/REPOSITORY_MANIFEST_PLAN.md

@@ -0,0 +1,272 @@
+# Forge em repositórios existentes: manifesto, mapas e Agent Fabric
+
+Data: 2026-10-06
+
+Status: proposta revisada por subagent independente; ajustes incorporados em 2026-10-06. Nenhum comando ou campo proposto neste documento implica suporte atual.
+
+## 1. Objetivo
+
+Permitir que Codex prepare um repositório existente para usar análise, mapas, consultas CAIR e contexto do Agent Fabric, preservando sua arquitetura, ferramentas e runtime. Vue/Nuxt, Java/Spring e Docker/Compose devem estar presentes no primeiro piloto integrado, além de TypeScript/JavaScript.
+
+O usuário permanece no chat do Codex e pede, por exemplo: “Prepare este projeto para usar os mapas do Forge”. O agente descobre a estrutura, gera um `forge.manifest.json`, valida o documento e solicita análise. O Forge deriva mapas do código; o agente usa os mapas para localizar funcionalidades, planejar alterações e selecionar verificações.
+
+Não é necessária migração para commands, queries, banco ou runtime Forge. Descobrir operações não as transforma em ferramentas executáveis. Esta entrega de planejamento não autoriza implementação, publicação ou instalação de integrações em outros projetos.
+
+## 2. Evidência da implementação atual
+
+Repositório analisado: `C:/Users/stahl/Projects/forge`, versão local `0.1.0-alpha.68`.
+
+| Componente | Base existente | Lacuna |
+| --- | --- | --- |
+| Manifesto externo | Serviços, entries, schemas, HTTP/stdio e registro | Não representa análise de repositório sem serviço |
+| Brownfield import | Inventário, rotas, chamadas, riscos e candidatos | Orientado a migração; análise predominantemente textual |
+| Vue/Nuxt | Dependências e algumas páginas/componentes no frontend graph | Brownfield não coleta `.vue`; frontend graph assume `web` e bindings Forge |
+| Java/Spring | Controllers por annotations e inventário Maven | Regex, sem resolução semântica; Gradle ausente no inventário examinado |
+| App graph | Símbolos, módulos, referências, hashes e parsing incremental | Parser orientado a TypeScript/TSX; tipos parcialmente ligados ao runtime |
+| Test graph | Descoberta/classificação de testes | Extensões e diretórios específicos de TypeScript |
+| CAIR | Snapshot compacto, símbolos, referências e impacto | Leitura direta de artefatos do compilador Forge |
+| Docker | Backend de sandbox | Não equivale a grafo estático de Dockerfile/Compose |
+| Agent Fabric | Runtime compartilhado, registro de projetos, owners e clones | Falta integração explícita com os mapas propostos |
+
+Fontes relativas ao checkout Forge:
+
+- `src/forge/brownfield-import/index.ts` e `types.ts`.
+- `src/forge/compiler/external-manifest/{types,validate,registry}.ts`.
+- `schemas/forge-manifest.schema.json`.
+- `src/forge/compiler/frontend-graph/build.ts`.
+- `src/forge/compiler/app-graph/parser.ts` e `compiler/types/app-graph.ts`.
+- `src/forge/compiler/test-graph/build.ts`.
+- `src/forge/cair/snapshot.ts`.
+- `docs/brownfield-import.md` e `docs/forge-protocol.md`.
+
+Detalhe a corrigir: tipos/validador externo contemplam `commandArgs`, mas o JSON Schema examinado não declara o campo. Confirmar e alinhar schema, validadores, tipos, fixtures e documentação durante a implementação.
+
+Limites adicionais confirmados na revisão: o importador atual ignora `tests` e `__tests__` e lê arquivos `.env` e `.env.local` para extrair nomes de variáveis. Isso não prova emissão dos valores, mas viola a política proposta de não abrir esses arquivos. Reutilizar classificadores úteis após introduzir scanner configurável; não reutilizar a coleta atual sem correção. CAIR consulta fonte atual diretamente em definições e usa busca textual em referências; seu snapshot não garante que a resposta consultada pertença à mesma versão.
+
+## 3. Decisões de arquitetura
+
+### 3.1 Um manifesto, modalidades distintas
+
+Preservar o nome `forge.manifest.json`. Manter suporte ao protocolo de serviço 1.0. Introduzir uma modalidade discriminada de repositório, com schema próprio dentro do mesmo sistema de manifestos. A versão `2.0` abaixo é ilustrativa: decidir o versionamento final após verificar consumidores e política de compatibilidade.
+
+Internamente, separar `ServiceManifest` e `RepositoryManifest`; nunca fazer um consumidor de serviços assumir `manifest.service.name` em um manifesto de repositório. Um projeto analisado pode referenciar contratos de serviços existentes por arquivos relativos, sem transformar seus candidatos em serviços automaticamente.
+
+Introduzir loader discriminado antes do registry atual: descoberta automática de `forge.manifest.json` deve classificar o documento; registry/runtime externos recebem somente ServiceManifest. Um root RepositoryManifest não pode quebrar a geração de uma aplicação Forge nem tornar-se serviço inválido. Quando já existir um root ServiceManifest, discovery não o sobrescreve: oferecer documento composto versionado ou configuração externa/referências explícitas. Esta escolha integra a decisão de schema de E1.
+
+Exemplo conceitual, ainda não aceito pela CLI atual:
+
+```json
+{
+  "forgeProtocol": "2.0",
+  "kind": "repository",
+  "components": [
+    { "id": "frontend", "root": "frontend", "adapters": ["vue", "typescript"] },
+    { "id": "backend", "root": "backend", "adapters": ["java", "spring", "maven"] },
+    { "id": "infra", "root": ".", "adapters": ["docker"], "files": ["compose.yaml", "backend/Dockerfile"] }
+  ],
+  "exclude": ["**/node_modules/**", "**/target/**"],
+  "checks": [
+    { "id": "frontend-tests", "component": "frontend", "argv": ["npm", "test"] }
+  ]
+}
+```
+
+O manifesto declara configuração, raízes, aliases/overrides necessários e verificações sugeridas. Não contém inventário manual de todas as funções. Contratos de APIs e integrações são opcionais. Validar IDs únicos, caminhos, limites e conflitos entre componentes sobrepostos.
+
+Usar caminhos relativos ao repositório. A localização absoluta pertence ao registro host-local do Fabric. Se o usuário não desejar arquivo no projeto, permitir um manifesto externo explicitamente associado a uma raiz registrada; não inferir raízes externas a partir de texto arbitrário.
+
+### 3.2 Descoberta determinística e complemento pelo Codex
+
+1. Resolver a raiz desejada e ler instruções do projeto.
+2. Descobrir manifests de pacotes, arquivos de build, componentes, frameworks e infraestrutura.
+3. Entregar inventário e lacunas ao agente.
+4. Codex prepara o manifesto e documenta decisões que a descoberta não resolve.
+5. Forge valida e calcula o grafo.
+6. Codex consulta o resultado e corrige configuração quando necessário.
+
+Definir um único resolvedor de raiz para todas as novas operações: raiz explícita ou projectId primeiro; descoberta ascendente limitada a marcadores reconhecidos quando omitida. Não exigir package.json para Java/infra. A CLI atual usa cwd em diversos caminhos; não assumir descoberta universal. Para análise estática, permitir diretório sem Git; preservar exigência Git+HEAD do Fabric para clones gerenciados. Relatar separadamente análise disponível e execução gerenciada disponível.
+
+Não aceitar root e projectId divergentes; se ambos forem fornecidos, exigir identidade canônica equivalente. Definir paragem de descoberta em worktrees/submódulos e diagnóstico para manifestos ancestrais ambíguos. Um manifesto externo não redefine a raiz para o diretório onde o arquivo está salvo.
+
+Registrar proveniência de declarações do agente e overrides. Não dar a essas declarações a mesma classificação de relações observadas no código. A configuração muda com a estrutura; mapas mudam com o conteúdo.
+
+### 3.3 Modelo comum de análise
+
+Criar um grafo neutro de repositório, separado das exigências do runtime Forge. Reutilizar hashing, serialização determinística, diagnósticos e primitives compatíveis. Adaptadores produzem fatos; uma fase de resolução combina fatos e identifica ambiguidades.
+
+Entidades: repository, component, package, file, symbol, page, UI component, endpoint, data model, test, container service, build stage, image, volume e network.
+
+Relações: contains, imports, references, calls, renders, routes-to, implements, tests, builds, runs, depends-on e connects-to. Distinguir ligação declarada de configuração, referência resolvida e possibilidade inferida.
+
+Cada fato inclui ID determinístico, localização, hash de fonte, adaptador/versão e referências de evidência. Definir estabilidade de IDs em edição e comportamento em renomeação. Uma mudança de ID não pode produzir referência silenciosa a uma entidade diferente.
+
+Padronizar coordenadas de fonte: offsets UTF-16 e intervalos semiabertos para integração Node, com linha/coluna e conversão explícita dos offsets de parsers em bytes. Preservar CRLF e Unicode; source mapping de blocos Vue retorna sempre posições no SFC original. IDs abreviados CAIR, como S#1, são handles locais ao snapshot: chamadas dependentes exigem snapshotId e não podem reaplicar o handle em outra ordenação.
+
+Usar categorias de evidência `declared`, `syntactic`, `resolved` e `inferred`, com resolução `complete`, `partial` ou `unresolved`. Não apresentar scores fixos como probabilidades calibradas.
+
+### 3.4 Cobertura como resultado de primeira classe
+
+Todo snapshot inclui arquivos encontrados, analisados, ignorados, com erro e sem adaptador; razões de exclusão; recursos não suportados; relações não resolvidas e diagnósticos. Mapas parciais continuam úteis, mas não podem ser apresentados como compreensão completa.
+
+## 4. Adaptadores do primeiro piloto
+
+### 4.1 TypeScript/JavaScript
+
+Reaproveitar extração existente quando independente do runtime. Identificar módulos, exports, símbolos e imports. Resolução de aliases, workspaces e imports deve seguir configurações reais, sem exigir package.json na raiz de todos os projetos. Diferenciar parsing de resolução semântica; escolher ferramentas após um spike de compatibilidade e distribuição.
+
+### 4.2 Vue/Nuxt
+
+Analisar `.vue` com entendimento de template, script, script setup e style. Preservar posições no arquivo original ao trabalhar com blocos. Identificar imports, componentes usados, props, emits, composables, stores, Vue Router e convenções Nuxt. Tratar aliases e autoimports conforme configuração.
+
+Relacionar páginas a componentes e clientes HTTP. Componentes dinâmicos, URLs construídas e autoimports não resolvidos permanecem explícitos no relatório. Não executar configuração arbitrária para apenas descobrir estrutura.
+
+Descobrir testes Vitest/Jest e uso de Vue Test Utils quando presentes. Distinguir teste encontrado, associação estática ao componente e cobertura observada por execução; nenhuma associação por nome é prova de cobertura executada.
+
+### 4.3 Java/Spring
+
+Nível inicial: parser sintático para packages, classes, interfaces, métodos, imports e annotations; endpoints, DTOs e relações Spring quando observáveis. Inventário Maven/Gradle multimódulo. Leitura estática de arquivos Gradle tem limites por ser uma DSL executável; declarar esses limites.
+
+Nível opcional: resolução semântica com ferramentas Java disponíveis, classpath e configuração explicitamente preparados. Não executar wrappers ou builds durante uma análise declarada estática. Reflection, Lombok, proxies e código gerado entram no relatório de cobertura. Chamada a interface não garante qual implementação recebe a chamada.
+
+Descobrir testes JUnit/TestNG, source sets e fixtures declarados. Reportar ligação sintática/inferida a classes separadamente de cobertura observada e de resolução semântica.
+
+### 4.4 Docker/Compose
+
+Analisar Dockerfile: FROM/estágios, contextos, COPY, referências a variáveis, entrypoint e command como informação. Analisar Compose: serviços, build contexts, imagens, portas, volumes, redes, profiles, depends_on e referências a secrets/configs/env.
+
+Cobrir arquivos adicionais e overrides por uma seleção explícita de cenário. Preservar interpolação não resolvida sem ler valores sensíveis automaticamente. Diferenciar porta interna de publicada e rede interna de endereço acessível pelo navegador. `depends_on` não prova tráfego nem disponibilidade.
+
+O cenário também identifica profiles Spring e modos Vite/Nuxt reconhecidos estaticamente, ordem de overlays e arquivos Compose selecionados. Esse conjunto e seus hashes fazem parte do snapshot; ambientes diferentes não compartilham silenciosamente a mesma resolução. Valores desconhecidos permanecem desconhecidos.
+
+Análise estática não inicia Docker, não constrói imagens e não faz pull. Inspeção observada de containers ou ferramentas externas seria operação separada e identificada.
+
+## 5. Resolução entre tecnologias
+
+Exemplo esperado:
+
+```text
+Pedidos.vue -> usePedidos -> cliente GET /api/pedidos
+            -> PedidoController -> PedidoService -> PedidoRepository
+
+Compose api -> build backend/Dockerfile -> componente backend
+```
+
+Relacionar por método HTTP, padrão de caminho, base URL, proxy, componente e cenário de configuração. Consumir OpenAPI local opcionalmente. Não usar apenas prefixos de URL: o detector atual pode gerar associação incorreta e deve ser substituído na fase integrada.
+
+Ligações sugeridas pelo modelo podem enriquecer a análise como declarações rastreáveis; não substituem resolução. Quando dois serviços oferecem o mesmo caminho, manter ambiguidade até haver contexto suficiente.
+
+## 6. Artefatos e consultas
+
+Armazenar artefatos locais em uma área dedicada, proposta `.forge/repository/`, sem escrever em `src/forge/_generated`. Manifesto pode ser versionado; cache e estado operacional são locais. Definir formato canônico, escritas atômicas e publicação de um snapshot completo somente após validação.
+
+Oferecer cache host-local explicitamente configurado quando não houver autorização ou interesse em escrever no repositório. Discovery/validate possuem modo sem escrita, inclusive sem telemetria local/recorder Delta; analyze declara seu destino de artefatos. A CLI atual pode registrar operações no Delta mesmo em comandos de leitura, com bypass existente `--no-delta`/`FORGE_DELTA=0`; a nova superfície precisa preservar o contrato sem escrita de ponta a ponta. Não editar `.gitignore` automaticamente.
+
+Separar provider de análise `forge-application` de `repository` na integração CAIR. Preservar queries atuais onde os conceitos correspondem; recursos dependentes do runtime e mutações CAIR não suportadas devem retornar capacidade indisponível em vez de fingir suporte.
+
+O provider deve cobrir snapshot, queries, resolução de referências, leitura de fontes e capabilities/actions. Alterar apenas snapshot não basta. Consultas precisam carregar snapshotId e detectar divergência com a fonte atual antes de devolver resultados. Não rotular a busca textual atual de Q REFS como referência semanticamente resolvida. No primeiro release repository, ações CAIR mutantes ficam indisponíveis; ações de leitura continuam disponíveis conforme cobertura.
+
+Consultas prioritárias: overview, locate, symbol, references, routes, dependencies, impact, tests, infrastructure e coverage. Respostas compactas, orçamento de contexto, paginação/cursor e referências ao código. Não despejar o grafo inteiro em todo prompt.
+
+Critérios de consulta incluem duas funções homônimas sem mistura, ausência de comentários/strings como referências resolvidas e rejeição de handle/snapshot obsoleto. Fonte posterior à análise não pode ser recortada usando offsets antigos.
+
+Comandos ilustrativos, não existentes nesta proposta:
+
+```text
+forge manifest discover --json
+forge manifest validate forge.manifest.json --json
+forge repository analyze --json
+forge repository context --query "autenticação" --json
+```
+
+A sintaxe final deve respeitar a CLI atual e evitar superfícies duplicadas com `import analyze` e CAIR. Definir depreciação ou aliases somente depois de verificar consumidores.
+
+## 7. Integração Agent Fabric e skill
+
+Skill conduz descoberta, geração e consultas; não exige que o usuário escreva JSON. Runtime e skill continuam compartilhados. Registro por projeto e seleção explícita de projectId mantêm isolamento CLI/MCP.
+
+Ao planejar um workflow, Fabric obtém contexto limitado à tarefa: snapshot, arquivos, relações, checks sugeridos e lacunas. Cada worker recebe contexto do seu próprio clone/snapshot; após composição de alterações upstream, renovar análise relevante. Não reutilizar o grafo do checkout original como se descrevesse um clone modificado.
+
+Maps ajudam a sugerir writeScope, dependências e revisão, mas não alteram silenciosamente obrigações de aceitação. Impacto estimado não autoriza pular verificações requeridas. Checks declarados não executam durante descoberta; execução é uma atividade do workflow com argv explícito e escopo autorizado.
+
+Hooks são opcionais para atualização; não necessários à análise. Não instalar hooks/MCP como efeito colateral. MCP pode expor queries de análise roteadas pelo registro existente.
+
+## 8. Incrementalidade, consistência e múltiplos repositórios
+
+Snapshot considera conteúdo local, incluindo mudanças não commitadas, manifesto, configs e versões dos adaptadores. Commit Git é metadado, não chave suficiente de validade.
+
+Reusar parsing por hash de arquivo. Invalidar resolução quando configuração, aliases, manifests de dependências ou contratos mudam. Detectar mudanças durante leitura; repetir o trecho necessário ou marcar snapshot inconsistente. Publicar artefatos atomicamente e serializar concorrência no cache, sem reutilizar locks de execução indiscriminadamente.
+
+Cada repositório tem identidade e snapshot próprios. Multi-repo usa referências explícitas a projetos registrados e contratos locais. Resposta identifica origem/versão de cada mapa; não afirma snapshot global atômico entre repositórios. Mudança em outro checkout não é sincronizada automaticamente.
+
+## 9. Limites de leitura e execução
+
+Respeitar raízes canônicas, exclusões explícitas e tratamento de symlinks. Não seguir referências para fora do escopo sem configuração autorizada. Limites de quantidade/tamanho/tempo aparecem nos diagnósticos, nunca como truncamento invisível.
+
+Não coletar valores de credenciais, `.env` reais, secrets ou payloads operacionais. Nomes/referências de variáveis podem ser mapeados. Sanitizar fragmentos de Docker/config quando contiverem valores sensíveis; não incluir fonte completa por padrão nos pacotes de contexto.
+
+Análise estática não executa package scripts, Gradle, Maven, arquivos de configuração JS, comandos de Docker ou adaptadores arbitrários. Adaptadores iniciais são embutidos/versionados. Provedores semânticos que exigem preparação são operações separadas, explícitas e com proveniência. A coleta de fontes precisa incluir testes conforme configuração e separar exclusões de credenciais da simples classificação de arquivos; não pode herdar cegamente o scanner brownfield atual.
+
+## 10. Entregas e critérios de aceite
+
+| Etapa | Entrega | Critério |
+| --- | --- | --- |
+| E1 | Schema discriminado, compatibilidade, root resolver e scanner configurável | Manifestos 1.0 continuam válidos; repo sem serviço/package.json validável; testes incluídos; arquivos sensíveis não abertos; caminhos e IDs verificados |
+| E2 | Grafo neutro, snapshot coerente e adaptadores iniciais | Vue + Spring + Compose presentes; hashes/cenário/IDs determinísticos; escrita atômica e mudança durante análise detectada; fixtures com fatos esperados e casos negativos |
+| E3 | CAIR/provider completo e contexto | Consultas compactas funcionam sem runtime Forge; leituras ligadas a snapshot; referências textuais diferenciadas; ações não suportadas indisponíveis |
+| E4 | Skill/Fabric | Contexto correto para checkout e clones; roteamento por projeto; zero execução implícita |
+| E5 | Otimização incremental e evolução semântica | Melhorar reutilização e resolução sobre a consistência mínima já entregue; cobertura, orçamento e custo observáveis |
+
+O primeiro piloto integrado deve usar Vue + Java/Spring + Compose, incluindo frontend/backend em diretórios independentes. Fixture hermética evita depender de produção; piloto em repositório real só com escopo escolhido e autorizado.
+
+Validação necessária:
+
+- Manifests antigos e novos; schema/tipos/validador concordantes.
+- Vue script setup, aliases, autoimports e componentes dinâmicos.
+- CLI em subdiretório, Java sem package.json, diretório sem Git analisável e execução Fabric corretamente indisponível sem Git+HEAD.
+- Scanner inclui testes declarados sem abrir `.env` reais; manifesto existente não é sobrescrito durante discovery.
+- Maven multimódulo, Gradle com lacunas explícitas e Java semântico indisponível.
+- Mesmo endpoint com métodos distintos, parâmetros, proxies e serviços ambíguos.
+- Docker multistage, Compose overrides/profiles, ports, networks e interpolação.
+- Relações frontend/backend/infra confrontadas com ground truth revisado.
+- Arquivos excluídos, symlinks, configurações sensíveis e limites.
+- Mudança não commitada, delete/rename, concurrent update e cache invalidation.
+- Q DEF/Q REFS após mudança de fonte: não devolver evidência de snapshot antigo como se atual; resultados textuais não recebem assurance semântica.
+- Homônimos, comentários/strings, handles CAIR de snapshots distintos, Unicode/CRLF e source mapping Vue.
+- Testes Vue e Java encontrados sem afirmar cobertura executada.
+- Cenários diferentes não reutilizam relações incompatíveis; discovery/validate sem escrita não criam Delta/cache nem alteram `.gitignore`.
+- Root RepositoryManifest não quebra registry/runtime de serviços; root ServiceManifest existente é preservado.
+- Independência do framework: nenhum arquivo/dependência runtime Forge exigido no projeto.
+- Fabric clones: contexto pré/pós upstream e publicação não usam evidência obsoleta.
+- Multi-repo: isolamento, IDs, raízes e snapshots distintos.
+
+Medir precisão das relações resolvidas, cobertura das relações conhecidas, proporção de ambiguidades, custo da primeira análise, custo incremental e tamanho dos pacotes de contexto. Não fixar metas numéricas antes de estabelecer baseline reproduzível; definir metas antes do aceite do piloto.
+
+## 11. Riscos e decisões pendentes
+
+- Extensão de manifestos deve evitar regressão na descoberta automática do root manifesto e nos consumers que assumem serviço.
+- Escolha de parsers/semantic providers exige spike de qualidade, Windows/Node, distribuição npm e licenças; não adicionar toolchain pesada ao caminho básico sem justificativa.
+- Vue/Nuxt e Java/Spring possuem recursos dinâmicos que impedirão completude estática.
+- Monorepos e configurações alternativas exigem descoberta por componente e seleção explícita de cenário.
+- Artefatos podem expor informação sensível se emitirem snippets sem sanitização.
+- Relação com `.forge/fabric.json`: esse arquivo continua configuração de execução; manifesto declara análise e sugestões. Definir precedência para checks sugeridos e evitar duplicar environment/maxConcurrency.
+- API de grafo e versão de manifestos devem ser escolhidas antes de ampliar consumidores.
+- Mapas de conhecimento não habilitam operações executáveis; adaptadores externos atuais preservam seu contrato separado.
+
+## 12. Resultado esperado
+
+Codex gera e mantém a configuração; Forge calcula mapas verificáveis e informa lacunas; CAIR fornece navegação compacta; Agent Fabric usa contexto atualizado para trabalhar. Vue, Java e Docker fazem parte da cobertura inicial, sem migração do projeto para o framework.
+
+## 13. Revisão independente
+
+Concluída pelo subagent `review_repository_manifest_plan` em 2026-10-06, por leitura do código atual, sem testes/builds/containers/CI. Parecer: arquitetura adequada com oito ajustes recomendados, incorporados neste documento:
+
+1. Provider CAIR completo, fonte vinculada a hash e referências com assurance correta.
+2. Resolvedor de raiz e distinção análise sem Git versus execução Fabric Git+HEAD.
+3. Scanner configurável incluindo testes, sem abertura de `.env` reais.
+4. Loader discriminado e coexistência de manifestos sem regressão de serviços.
+5. Consistência mínima em E2/E3 antes do Fabric; otimização incremental em E5.
+6. Descoberta de testes Vue/Java e convenção de coordenadas/handles.
+7. Modo sem escrita incluindo recorder Delta e opção de cache host-local.
+8. Cenário de configuração como parte da identidade do snapshot.
+
+Evidências detalhadas e relatório em `FORGE_REPOSITORY_MANIFEST_REVIEW.md`, no mesmo diretório. A revisão é documental e não constitui validação da implementação futura. Versionamento definitivo, escolha de parsers e metas de desempenho permanecem decisões explicitamente pendentes.

package/docs/changelog.md

@@ -4,6 +4,38 @@ Release history for the `forgeos` npm package.
 
 The canonical source file in the repository is `CHANGELOG.md`.
 
+## Unreleased
+
+- Explicit repository runtime plans, isolated-copy command execution and bounded Nuxt,
+  Spring, Docker and HTTP artifact context, with current-source/manifest/scenario binding
+  and expiration. CLI and MCP share execution opt-in; prepared Fabric workers consume
+  matching saved observations without starting exporters.
+
+- Lazy large-map hydration, compatible streaming fingerprints, automatic retained
+  cache cleanup and source-bound paired agent benchmark planning/reporting. The
+  benchmark evaluates supplied evidence without implicit model/check execution.
+
+- Deterministic scoped repository retrieval, precise case-level test associations,
+  static Nuxt/HTTP resolution, declared client mappings and informative check requirements.
+- Validated partitions for large maps and root-neutral facts, prepared-clone parse
+  reuse and the read-only `repository quality --cases` benchmark. Static quality remains
+  partial; suggested checks and models are not executed by analysis.
+
+## 0.1.0-alpha.69
+
+- Repository manifests and static maps for existing TypeScript/JavaScript, Vue/Nuxt,
+  Java/Spring/Maven/Gradle and Docker/Compose projects without adopting the Forge runtime.
+- Snapshot-bound CAIR queries, incremental parsing, bounded project-routed MCP context
+  and validated cache identity/source provenance.
+- Agent Fabric workers receive the map of their own prepared clone; the shared personal
+  skill also supports analysis in projects without Git.
+- Static local TypeScript configuration inheritance, Vue conditional branches and
+  multiline Dockerfile instructions; ambiguous and dynamic behavior remains explicit.
+- Local release staging preserves npm exclusions; the installed-package smoke checks
+  external Vue + Spring + Compose maps in addition to the application quickstart.
+- Patched transitive dependency resolutions for provider utilities, PostCSS, Nano ID
+  and URI parsing remove the advisories reported by the checked-in lockfile audit.
+
 ## 0.1.0-alpha.63
 
 - `forge status` now verifies generated output deterministically instead of