dd-harness 0.1.3 → 0.2.0

package/LICENSE

@@ -1,11 +1,11 @@
-Copyright (c) 2026 Diego Dias
-
-Todos os direitos reservados.
-
-Este software é publicado no registro npm apenas para distribuição ao seu autor e a
-quem ele autorizar expressamente. Nenhuma permissão de uso, cópia, modificação,
-distribuição ou criação de obras derivadas é concedida por esta publicação.
-
-All rights reserved. This software is published to the npm registry for distribution
-to its author and to those he expressly authorizes. No permission to use, copy,
-modify, distribute, or create derivative works is granted by this publication.
+Copyright (c) 2026 Diego Dias
+
+Todos os direitos reservados.
+
+Este software é publicado no registro npm apenas para distribuição ao seu autor e a
+quem ele autorizar expressamente. Nenhuma permissão de uso, cópia, modificação,
+distribuição ou criação de obras derivadas é concedida por esta publicação.
+
+All rights reserved. This software is published to the npm registry for distribution
+to its author and to those he expressly authorizes. No permission to use, copy,
+modify, distribute, or create derivative works is granted by this publication.

package/README.md

@@ -1,64 +1,64 @@
-# dd-harness
-
-Materializa a **política**, o **briefing** e o **Brain** do
-[dd-harness](https://dd-harness.vercel.app) dentro do seu repositório, para que a sessão
-do agente de código abra já sabendo as regras e as decisões do projeto.
-
-Sem dependência: `fetch`, `crypto` e `fs` são do Node. Um CLI que vive pinado em
-repositório alheio precisa envelhecer bem, e cada dependência é uma chance de não
-envelhecer.
-
-## Instalação
-
-```sh
-npm install -g dd-harness
-```
-
-Ou sem instalar nada:
-
-```sh
-npx dd-harness sync
-```
-
-Requer Node 20 ou mais novo.
-
-## Uso
-
-```sh
-dd-harness init --tenant <espaço> --projeto <projeto>   # prepara o repositório
-dd-harness login --token <token>                        # credencial desta máquina
-dd-harness sync                                         # escreve os artefatos
-dd-harness check [--commit <sha>]                       # mede âncoras e reporta deriva
-dd-harness status                                       # só lê: o que espera julgamento
-```
-
-O token pessoal nasce na tela `/tokens` do serviço. Ele é guardado em
-`~/.dd-harness/credentials.json` (modo `0600`, por origem de API) — **fora** do
-repositório, para não viajar num commit.
-
-## O que aparece no seu repositório
-
-```
-.dd-harness.json      configuração (tenant, projeto, api) — escrita à mão
-CLAUDE.md             SEU arquivo; o sync nunca o reescreve
-dd-harness/           tudo o que é gerado
-  politica.md
-  BRIEFING.md
-  brain/
-  manifest.json
-```
-
-Na raiz fica apenas o **seu** `CLAUDE.md`, que importa a política com a linha
-`@dd-harness/politica.md`. Isso deixa conviverem a parte gerenciada e o que o
-repositório tem de próprio — adotar um projeto existente é acrescentar uma linha, não
-sobrescrever nada.
-
-O `sync` confere esse ponteiro a cada execução, inclusive quando o serviço não mudou:
-import quebrado ou linha ausente faz a sessão abrir **sem política e sem avisar**. Isso
-foi medido, não suposto.
-
-## Deriva
-
-`dd-harness check` mede as âncoras das memórias contra o estado real do repositório e
-reporta o que saiu do lugar. Com `--commit <sha>` ele também cruza as âncoras com o diff
-daquele commit — a memória volta ao code review. Nada bloqueia: avisa.
+# dd-harness
+
+Materializa a **política**, o **briefing** e o **Brain** do
+[dd-harness](https://dd-harness.vercel.app) dentro do seu repositório, para que a sessão
+do agente de código abra já sabendo as regras e as decisões do projeto.
+
+Sem dependência: `fetch`, `crypto` e `fs` são do Node. Um CLI que vive pinado em
+repositório alheio precisa envelhecer bem, e cada dependência é uma chance de não
+envelhecer.
+
+## Instalação
+
+```sh
+npm install -g dd-harness
+```
+
+Ou sem instalar nada:
+
+```sh
+npx dd-harness sync
+```
+
+Requer Node 20 ou mais novo.
+
+## Uso
+
+```sh
+dd-harness init --tenant <espaço> --projeto <projeto>   # prepara o repositório
+dd-harness login --token <token>                        # credencial desta máquina
+dd-harness sync                                         # escreve os artefatos
+dd-harness check [--commit <sha>]                       # mede âncoras e reporta deriva
+dd-harness status                                       # só lê: o que espera julgamento
+```
+
+O token pessoal nasce na tela `/tokens` do serviço. Ele é guardado em
+`~/.dd-harness/credentials.json` (modo `0600`, por origem de API) — **fora** do
+repositório, para não viajar num commit.
+
+## O que aparece no seu repositório
+
+```
+.dd-harness.json      configuração (tenant, projeto, api) — escrita à mão
+CLAUDE.md             SEU arquivo; o sync nunca o reescreve
+dd-harness/           tudo o que é gerado
+  politica.md
+  BRIEFING.md
+  brain/
+  manifest.json
+```
+
+Na raiz fica apenas o **seu** `CLAUDE.md`, que importa a política com a linha
+`@dd-harness/politica.md`. Isso deixa conviverem a parte gerenciada e o que o
+repositório tem de próprio — adotar um projeto existente é acrescentar uma linha, não
+sobrescrever nada.
+
+O `sync` confere esse ponteiro a cada execução, inclusive quando o serviço não mudou:
+import quebrado ou linha ausente faz a sessão abrir **sem política e sem avisar**. Isso
+foi medido, não suposto.
+
+## Deriva
+
+`dd-harness check` mede as âncoras das memórias contra o estado real do repositório e
+reporta o que saiu do lugar. Com `--commit <sha>` ele também cruza as âncoras com o diff
+daquele commit — a memória volta ao code review. Nada bloqueia: avisa.

package/dist/api.d.ts

@@ -0,0 +1,21 @@
+import { type ConfigDoRepo } from "./config.js";
+/**
+ * A fronteira com o servico: ler credencial e falar HTTP.
+ *
+ * Cada comando reimplementava as mesmas tres linhas — le config, le token, monta `fetch`
+ * com `Authorization` — e cada copia era uma chance de divergir na mensagem de erro.
+ * Aqui elas existem uma vez, e o servidor MCP consome as mesmas funcoes que o CLI: as
+ * duas portas falam com a API pelo mesmo caminho, entao corrigir uma corrige a outra.
+ */
+export type Credencial = {
+    config: ConfigDoRepo;
+    token: string;
+};
+export declare function credencial(raiz: string): Promise<Credencial>;
+/**
+ * O `erro` que a API devolve no corpo e mais util que o status, e e o que o agente le.
+ * Sem corpo interpretavel, o status ao menos diz que houve resposta.
+ */
+export declare function recusa(resposta: Response): Promise<never>;
+export declare function cabecalhos(token: string, comCorpo?: boolean): Record<string, string>;
+export declare function pede(url: string | URL, init?: RequestInit, tentativas?: number): Promise<Response>;

package/dist/api.js

@@ -0,0 +1,69 @@
+import { leConfigDoRepo, leToken } from "./config.js";
+export async function credencial(raiz) {
+    const config = await leConfigDoRepo(raiz);
+    const token = await leToken(config.api);
+    if (!token) {
+        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
+    }
+    return { config, token };
+}
+/**
+ * O `erro` que a API devolve no corpo e mais util que o status, e e o que o agente le.
+ * Sem corpo interpretavel, o status ao menos diz que houve resposta.
+ */
+export async function recusa(resposta) {
+    const { erro } = (await resposta.json().catch(() => ({})));
+    throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
+}
+export function cabecalhos(token, comCorpo = false) {
+    return comCorpo
+        ? { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }
+        : { Authorization: `Bearer ${token}` };
+}
+/**
+ * `fetch` com nova tentativa para falha transitoria.
+ *
+ * Medido em uso real: um `ECONNRESET` de conexao ociosa derrubou um `arquivar` que
+ * funcionou na segunda tentativa manual. Sem retry, falha de rede de um segundo vira erro
+ * final — e para um agente isso e a diferenca entre seguir sozinho e parar para pedir
+ * ajuda. Com varios agentes concorrendo, transitorio deixa de ser raro.
+ *
+ * O que NAO e repetido, e o cuidado que importa:
+ *
+ * - Erro de aplicacao (4xx). Token invalido ou memoria fora dos filtros nao melhora na
+ *   segunda tentativa; repetir so atrasa a mensagem que o agente precisa ler.
+ * - 5xx em requisicao que ESCREVE. `POST /memorias` pode ter gravado antes de a resposta
+ *   se perder, e repetir criaria duas. Perder a resposta de uma escrita que funcionou e
+ *   ruim; gravar duas vezes e pior.
+ *
+ * Entao: repete falha de REDE (o `fetch` nem chegou a receber resposta) sempre, e 5xx
+ * apenas quando o metodo e seguro de repetir.
+ */
+const IDEMPOTENTES = new Set(["GET", "HEAD", "PUT", "DELETE"]);
+const espera = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function pede(url, init = {}, tentativas = 3) {
+    const metodo = (init.method ?? "GET").toUpperCase();
+    const podeRepetirErroDoServidor = IDEMPOTENTES.has(metodo);
+    let ultimoErro;
+    for (let tentativa = 1; tentativa <= tentativas; tentativa += 1) {
+        try {
+            const resposta = await fetch(url, init);
+            if (resposta.status >= 500 && podeRepetirErroDoServidor && tentativa < tentativas) {
+                await espera(tentativa * 400);
+                continue;
+            }
+            return resposta;
+        }
+        catch (erro) {
+            // Aqui o `fetch` falhou antes de qualquer resposta: DNS, conexao recusada,
+            // ECONNRESET. Nada foi processado do outro lado, entao repetir e seguro mesmo
+            // para POST.
+            ultimoErro = erro;
+            if (tentativa === tentativas)
+                break;
+            await espera(tentativa * 400);
+        }
+    }
+    const detalhe = ultimoErro instanceof Error ? ultimoErro.message : String(ultimoErro);
+    throw new Error(`não consegui falar com o serviço depois de ${tentativas} tentativas: ${detalhe}`);
+}

package/dist/buscar.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `dd-harness buscar "<pergunta>"` — recuperacao por relevancia.
+ *
+ * O contraponto da ancora: ela e exata e responde "que memorias falam deste arquivo?";
+ * esta responde "o que ja aprendemos sobre isto?", que e a pergunta de quem ainda esta
+ * entendendo o problema e nem sabe qual arquivo abrir.
+ *
+ * Devolve endereco, nao conteudo: quem quiser o corpo abre o arquivo que o `sync` ja
+ * materializou. Assim a busca continua barata e o Brain em disco continua sendo a fonte.
+ */
+export type Achado = {
+    endereco: string;
+    titulo: string;
+    resumo: string;
+};
+export declare function busca(raiz: string, consulta: string, limite?: number): Promise<{
+    semantica: boolean;
+    provedor: string | null;
+    achados: Achado[];
+}>;

package/dist/buscar.js

@@ -1,21 +1,15 @@
-import { leConfigDoRepo, leToken } from "./config.js";
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
 export async function busca(raiz, consulta, limite) {
-    const config = await leConfigDoRepo(raiz);
-    const token = await leToken(config.api);
-    if (!token) {
-        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
-    }
+    const { config, token } = await credencial(raiz);
     const url = new URL(`${config.api}/api/v1/busca`);
     url.searchParams.set("tenant", config.tenant);
     url.searchParams.set("projeto", config.projeto);
     url.searchParams.set("q", consulta);
     if (limite)
         url.searchParams.set("limite", String(limite));
-    const resposta = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
-    if (!resposta.ok) {
-        const { erro } = (await resposta.json().catch(() => ({})));
-        throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
-    }
+    const resposta = await pede(url, { headers: cabecalhos(token) });
+    if (!resposta.ok)
+        await recusa(resposta);
     const lido = (await resposta.json());
     return { semantica: lido.semantica, provedor: lido.provedor, achados: lido.resultados };
 }

package/dist/check.d.ts

@@ -0,0 +1,63 @@
+import { type Tocada } from "./diff.js";
+import type { Brain } from "./materializa.js";
+/**
+ * `dd-harness check` — resolve as âncoras contra a árvore de trabalho.
+ *
+ * Mede cada alvo e manda o resultado ao serviço, que julga. Nunca falha o processo por
+ * encontrar deriva: sai com 0 e imprime. Deriva avisa, não bloqueia — bloqueio antes de
+ * o mecanismo ter reputação ensina o reflexo do `--no-verify`.
+ */
+export type Medicao = {
+    pasta: string;
+    memoria: string;
+    valor: string;
+    sha: string | null;
+    detalhe?: string;
+};
+export type ResultadoDoCheck = {
+    medidas: number;
+    ausentes: string[];
+    novas: number;
+    base: number;
+    jaAbertas: number;
+    /** Observacoes que fecharam sozinhas: o alvo voltou a bater com a linha de base. */
+    fechadas: number;
+    /** Memorias que falam do que o commit mudou. Vazio quando nao ha `--commit`. */
+    tocadas: Tocada[];
+};
+export type ResultadoDoStatus = {
+    /**
+     * O tamanho do acervo, por pasta. Sem isto, um agente que pergunta "o que ha no Brain
+     * deste projeto?" nao tem comando que responda — e a saida que resta e contar arquivo
+     * em disco, que acerta por acidente: memoria gravada e nao sincronizada nao esta la, e
+     * memoria arquivada sai do disco mas continua no indice, em `## Historico`.
+     */
+    acervo: {
+        ativas: number;
+        arquivadas: number;
+        porPasta: {
+            pasta: string;
+            quantas: number;
+        }[];
+    };
+    comDeriva: {
+        pasta: string;
+        memoria: string;
+        titulo: string;
+        abertas: number;
+    }[];
+    vencidas: {
+        pasta: string;
+        memoria: string;
+        titulo: string;
+    }[];
+};
+/** Separado do IO para poder ser testado sem rede: dado um Brain, o que se mede. */
+export declare function medeAsAncoras(raiz: string, brain: Brain): Promise<Medicao[]>;
+/**
+ * Somente leitura, de proposito: e o que roda na ABERTURA da sessao. Medir e reportar
+ * ali dentro faria toda sessao escrever no servico antes de a pessoa digitar qualquer
+ * coisa — caro, e o tipo de efeito colateral que ninguem espera de "abrir o editor".
+ */
+export declare function status(raiz: string): Promise<ResultadoDoStatus>;
+export declare function check(raiz: string, commit?: string): Promise<ResultadoDoCheck>;

package/dist/check.js

@@ -1,3 +1,4 @@
+import { pede } from "./api.js";
 import { leConfigDoRepo, leToken } from "./config.js";
 import { caminhosDoCommit, memoriasTocadas } from "./diff.js";
 import { mede } from "./medir.js";
@@ -29,7 +30,7 @@ async function buscaOBrain(raiz) {
         throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
     }
     const parametros = `tenant=${encodeURIComponent(config.tenant)}&projeto=${encodeURIComponent(config.projeto)}`;
-    const resposta = await fetch(`${config.api}/api/v1/artefatos?${parametros}`, {
+    const resposta = await pede(`${config.api}/api/v1/artefatos?${parametros}`, {
         headers: { Authorization: `Bearer ${token}` },
     });
     if (resposta.status === 401) {
@@ -49,7 +50,17 @@ export async function status(raiz) {
     const { brain } = await buscaOBrain(raiz);
     const agora = Date.now();
     const ativas = brain.memorias.filter((m) => m.status === "ativa");
+    const porPasta = new Map();
+    for (const m of ativas)
+        porPasta.set(m.pasta, (porPasta.get(m.pasta) ?? 0) + 1);
     return {
+        acervo: {
+            ativas: ativas.length,
+            arquivadas: brain.memorias.length - ativas.length,
+            porPasta: [...porPasta]
+                .map(([pasta, quantas]) => ({ pasta, quantas }))
+                .sort((a, b) => a.pasta.localeCompare(b.pasta)),
+        },
         comDeriva: ativas
             .filter((m) => (m.deriva_aberta ?? 0) > 0)
             .map((m) => ({
@@ -74,7 +85,7 @@ export async function check(raiz, commit) {
     if (medicoes.length === 0) {
         return { medidas: 0, ausentes: [], novas: 0, base: 0, jaAbertas: 0, fechadas: 0, tocadas };
     }
-    const envio = await fetch(`${config.api}/api/v1/deriva`, {
+    const envio = await pede(`${config.api}/api/v1/deriva`, {
         method: "POST",
         headers: { ...cabecalhos, "Content-Type": "application/json" },
         body: JSON.stringify({

package/dist/config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Duas configuracoes, em lugares diferentes de proposito.
+ *
+ * `.dd-harness.json` fica **no repositorio** e e versionado: diz qual projeto aquele
+ * repo consome, e isso e informacao do repo, nao da pessoa.
+ *
+ * A credencial fica **na maquina** (`~/.dd-harness/credentials.json`, modo 0600) e nunca
+ * no repo: token e da pessoa e da maquina, e commitado seria segredo publicado.
+ */
+export type ConfigDoRepo = {
+    api: string;
+    tenant: string;
+    projeto: string;
+    /** Onde o gerado vive. Muda-la move tudo de uma vez, menos o CLAUDE.md da raiz. */
+    pasta: string;
+};
+export declare const CAMINHO_CONFIG = ".dd-harness.json";
+export declare const CAMINHO_MANIFESTO = "dd-harness/manifest.json";
+export declare function leConfigDoRepo(raiz: string): Promise<ConfigDoRepo>;
+/**
+ * Credencial por origem da API: a mesma maquina pode falar com uma instalacao local e
+ * com a de producao, e misturar token entre as duas daria 401 confuso.
+ */
+export declare function leToken(api: string): Promise<string | null>;
+export declare function guardaToken(api: string, token: string): Promise<string>;
+export type Manifesto = {
+    etag: string | null;
+    arquivos: Record<string, string>;
+};
+export declare const manifestoVazio: () => Manifesto;
+export declare function leManifesto(raiz: string): Promise<Manifesto>;
+export declare function gravaManifesto(raiz: string, manifesto: Manifesto): Promise<void>;
+export declare const hashDe: (conteudo: string) => string;

package/dist/curar.d.ts

@@ -0,0 +1,12 @@
+export declare function edita(raiz: string, caminho: string): Promise<{
+    endereco: string;
+    ancoras: number;
+}>;
+export type Arquivamento = {
+    motivo: "obsoleta" | "incorreta" | "fora_dos_filtros";
+    substituidaPor?: string;
+};
+export declare function arquiva(raiz: string, endereco: string, opcoes: Arquivamento): Promise<{
+    endereco: string;
+    motivo: string;
+}>;

package/dist/curar.js

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
-import { leConfigDoRepo, leToken } from "./config.js";
+import { relative } from "node:path";
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
+import { gravaManifesto, hashDe, leManifesto } from "./config.js";
 import { interpreta } from "./gravar.js";
 /**
  * Curadoria pelo agente: editar e arquivar.
@@ -12,25 +14,33 @@ import { interpreta } from "./gravar.js";
  * que o `sync` materializou e manda de volta. Um formato so para as duas operacoes, e o
  * que ele ja sabe ler.
  */
-async function credencial(raiz) {
-    const config = await leConfigDoRepo(raiz);
-    const token = await leToken(config.api);
-    if (!token) {
-        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
-    }
-    return { config, token };
-}
-async function recusa(resposta) {
-    const { erro } = (await resposta.json().catch(() => ({})));
-    throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
+/**
+ * Depois que o servico aceita, o arquivo em disco deixa de ser "edicao nao enviada" — e o
+ * manifesto tem que saber, senao o `sync` seguinte para com "editado a mao" e a unica saida
+ * que resta e descartar o arquivo. O ciclo materializa-corrige-envia travava justamente
+ * aqui, com o servico ja atualizado.
+ *
+ * Guarda o hash do que foi enviado, nao do que o servico devolveria: o `sync` seguinte
+ * reescreve o arquivo na forma canonica quando o ETag mudar.
+ */
+async function marcaComoEnviado(raiz, caminho, conteudo) {
+    const chave = relative(raiz, caminho).split("\\").join("/");
+    const manifesto = await leManifesto(raiz);
+    // Arquivo de fora do repositorio (um rascunho em /tmp, por exemplo) nao esta no
+    // manifesto e nao deve entrar: o manifesto descreve o que o `sync` materializou.
+    if (!manifesto.arquivos[chave])
+        return;
+    manifesto.arquivos[chave] = hashDe(conteudo);
+    await gravaManifesto(raiz, manifesto);
 }
 export async function edita(raiz, caminho) {
     const { config, token } = await credencial(raiz);
-    const memoria = interpreta(await readFile(caminho, "utf8"));
+    const cru = await readFile(caminho, "utf8");
+    const memoria = interpreta(cru);
     const endereco = `${memoria.pasta}/${memoria.slug}`;
-    const resposta = await fetch(`${config.api}/api/v1/memorias/${endereco}`, {
+    const resposta = await pede(`${config.api}/api/v1/memorias/${endereco}`, {
         method: "PATCH",
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        headers: cabecalhos(token, true),
         body: JSON.stringify({
             tenant: config.tenant,
             projeto: config.projeto,
@@ -45,13 +55,14 @@ export async function edita(raiz, caminho) {
     });
     if (!resposta.ok)
         await recusa(resposta);
+    await marcaComoEnviado(raiz, caminho, cru);
     return { endereco, ancoras: memoria.ancoras.length };
 }
 export async function arquiva(raiz, endereco, opcoes) {
     const { config, token } = await credencial(raiz);
-    const resposta = await fetch(`${config.api}/api/v1/memorias/${endereco}`, {
+    const resposta = await pede(`${config.api}/api/v1/memorias/${endereco}`, {
         method: "DELETE",
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        headers: cabecalhos(token, true),
         body: JSON.stringify({
             tenant: config.tenant,
             projeto: config.projeto,

package/dist/diff.d.ts

@@ -0,0 +1,25 @@
+import type { Brain } from "./materializa.js";
+/**
+ * Quais memorias falam do que este commit mudou.
+ *
+ * E a peca que devolve a memoria ao code review. Tirar o Brain do repositorio tirou o
+ * revisor que o diff dava de graca — no modelo file-based a memoria estava ali, no
+ * caminho de quem mexia. Aqui ela volta pelo cruzamento: caminho do diff contra ancora.
+ *
+ * Repare que isto NAO e deriva. Deriva e "o alvo mudou desde a linha de base"; isto e
+ * "voce acabou de mexer no que esta memoria guarda" — util mesmo quando a base ainda
+ * nem foi medida, e util mesmo que a memoria continue valendo.
+ */
+/** Caminhos alterados num commit. Vazio quando o git nao responde — nunca quebra. */
+export declare function caminhosDoCommit(raiz: string, commit: string): Promise<string[]>;
+export type Tocada = {
+    pasta: string;
+    memoria: string;
+    titulo: string;
+    ancora: string;
+};
+/**
+ * Cruza caminhos com ancoras. A ancora casa quando e o proprio caminho ou quando e um
+ * diretorio que o contem — `supabase/migrations` tem que casar com a migration nova.
+ */
+export declare function memoriasTocadas(brain: Brain, caminhos: string[]): Tocada[];

package/dist/gravar.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `dd-harness gravar <arquivo.md>` — o caminho pelo qual o agente registra memoria.
+ *
+ * A entrada e um markdown no mesmo formato que o `sync` materializa, porque e o formato
+ * que o agente ja sabe ler: frontmatter, corpo, os tres filtros, ancoras. Escrever um
+ * arquivo e o que ele fazia no modelo file-based; aqui o arquivo vira requisicao em vez
+ * de virar commit.
+ *
+ * O arquivo nao e deixado no repositorio: quem materializa e o `sync`, a partir do
+ * servico. Gravar e depois sincronizar traz a memoria de volta ja com o endereco real —
+ * e evita a divergencia de ter uma copia escrita a mao ao lado da copia gerada.
+ */
+export type MemoriaLida = {
+    slug: string;
+    titulo: string;
+    resumo: string;
+    pasta: string;
+    corpo: string;
+    dano: string;
+    invisibilidade: string;
+    externalidade: string;
+    ancoras: string[];
+    tambemEm: string[];
+};
+export declare function interpreta(texto: string): MemoriaLida;
+export declare function grava(raiz: string, caminho: string): Promise<{
+    endereco: string;
+    ancoras: number;
+    projetos: number;
+}>;

package/dist/gravar.js

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { leConfigDoRepo, leToken } from "./config.js";
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
 const OBRIGATORIOS = ["name", "titulo", "description", "pasta"];
 /** Frontmatter simples: `chave: valor` por linha. Sem lib de YAML — nao ha aninhamento. */
 function leFrontmatter(texto) {
@@ -74,15 +74,11 @@ export function interpreta(texto) {
     };
 }
 export async function grava(raiz, caminho) {
-    const config = await leConfigDoRepo(raiz);
-    const token = await leToken(config.api);
-    if (!token) {
-        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
-    }
+    const { config, token } = await credencial(raiz);
     const memoria = interpreta(await readFile(caminho, "utf8"));
-    const resposta = await fetch(`${config.api}/api/v1/memorias`, {
+    const resposta = await pede(`${config.api}/api/v1/memorias`, {
         method: "POST",
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        headers: cabecalhos(token, true),
         body: JSON.stringify({
             tenant: config.tenant,
             projeto: config.projeto,
@@ -98,10 +94,8 @@ export async function grava(raiz, caminho) {
             tambem_em: memoria.tambemEm,
         }),
     });
-    if (!resposta.ok) {
-        const { erro } = (await resposta.json().catch(() => ({})));
-        throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
-    }
+    if (!resposta.ok)
+        await recusa(resposta);
     const { endereco } = (await resposta.json());
     return {
         endereco,

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -2,11 +2,12 @@
 import { check, status } from "./check.js";
 import { leConfigDoRepo, guardaToken } from "./config.js";
 import { grava } from "./gravar.js";
-import { init } from "./init.js";
+import { init, SUGESTAO_MCP } from "./init.js";
 import { LINHA_DE_IMPORT } from "./materializa.js";
 import { busca } from "./buscar.js";
 import { arquiva, edita } from "./curar.js";
 import { criaPasta } from "./pasta.js";
+import { criaProjeto } from "./projeto.js";
 import { sync } from "./sync.js";
 /**
  * `dd-harness` — o cliente que materializa os artefatos no repositorio.
@@ -16,26 +17,29 @@ import { sync } from "./sync.js";
  * em repositorio alheio tem que envelhecer bem, e cada dependencia e uma chance de nao
  * envelhecer.
  */
-const AJUDA = `dd-harness — materializa política, briefing e Brain no repositório
-
-  dd-harness init --tenant <t> --projeto <p> [--api <url>]
-                                     prepara o repositório (config + CLAUDE.md)
-  dd-harness login --token <token>   guarda a credencial desta máquina
-  dd-harness pasta <slug> --definicao "o que entra e o que não entra"
-                                     cria a pasta que o gravar exige
-  dd-harness gravar <arquivo.md>     registra uma memória a partir de um markdown
-  dd-harness editar <arquivo.md>     corrige o que já está gravado
-  dd-harness arquivar <pasta>/<slug> --motivo <obsoleta|incorreta|fora_dos_filtros>
-                     [--substituida-por <pasta>/<slug>]
-                                     tira de circulação sem apagar
-  dd-harness buscar "<pergunta>"     acha memória por relevância, não por arquivo
-  dd-harness sync                    escreve os artefatos em disco
-  dd-harness check [--commit <sha>]  mede as âncoras e reporta a deriva
-  dd-harness status                  só lê: o que espera julgamento
-  dd-harness --help
-
-O gerado vive em dd-harness/. Na raiz fica só o seu CLAUDE.md, que importa a
-política com a linha ${LINHA_DE_IMPORT}
+const AJUDA = `dd-harness — materializa política, briefing e Brain no repositório
+
+  dd-harness login --token <token> [--api <url>]
+                                     guarda a credencial desta máquina
+  dd-harness projeto <slug> --nome "<nome>" [--tenant <t>] [--api <url>]
+                                     cria o projeto no serviço (antes do init)
+  dd-harness init --tenant <t> --projeto <p> [--api <url>]
+                                     prepara o repositório (config + CLAUDE.md)
+  dd-harness pasta <slug> --definicao "o que entra e o que não entra"
+                                     cria a pasta que o gravar exige
+  dd-harness gravar <arquivo.md>     registra uma memória a partir de um markdown
+  dd-harness editar <arquivo.md>     corrige o que já está gravado
+  dd-harness arquivar <pasta>/<slug> --motivo <obsoleta|incorreta|fora_dos_filtros>
+                     [--substituida-por <pasta>/<slug>]
+                                     tira de circulação sem apagar
+  dd-harness buscar "<pergunta>"     acha memória por relevância, não por arquivo
+  dd-harness sync                    escreve os artefatos em disco
+  dd-harness check [--commit <sha>]  mede as âncoras e reporta a deriva
+  dd-harness status                  só lê: o tamanho do Brain e o que espera julgamento
+  dd-harness --help
+
+O gerado vive em dd-harness/. Na raiz fica só o seu CLAUDE.md, que importa a
+política com a linha ${LINHA_DE_IMPORT}
 `;
 /** O aviso existe porque o import falha em silêncio — foi medido, não suposto. */
 function avisaSobreOPonteiro(ponteiro) {
@@ -72,17 +76,17 @@ function avisaSobreOPonteiro(ponteiro) {
  * nosso: escrever la dentro sem a pessoa pedir e o mesmo tipo de invasao que
  * sobrescrever o CLAUDE.md dela. Quem cola, decide.
  */
-const GANCHOS = `
-Opcional — dois ganchos que valem a pena:
-
-  .git/hooks/post-commit   (avisa quais memórias falam do que você mudou)
-    #!/bin/sh
-    dd-harness check --commit "$(git rev-parse HEAD)" || true
-
-  .claude/settings.json    (na abertura da sessão, o que espera julgamento)
-    "hooks": { "SessionStart": [{ "hooks": [{ "type": "command",
-      "command": "dd-harness status" }] }] }
-
+const GANCHOS = `
+Opcional — dois ganchos que valem a pena:
+
+  .git/hooks/post-commit   (avisa quais memórias falam do que você mudou)
+    #!/bin/sh
+    dd-harness check --commit "$(git rev-parse HEAD)" || true
+
+  .claude/settings.json    (na abertura da sessão, o que espera julgamento)
+    "hooks": { "SessionStart": [{ "hooks": [{ "type": "command",
+      "command": "dd-harness status" }] }] }
+
 Os dois terminam em sucesso mesmo com deriva: avisam, não bloqueiam.`;
 function argumento(argv, nome) {
     const i = argv.indexOf(`--${nome}`);
@@ -106,14 +110,30 @@ async function comandoInit(argv) {
         "ja-tinha-a-linha": "mantido CLAUDE.md — já importava a política",
     }[r.claudeMd]);
     console.log("\nAgora: dd-harness login --token <token> && dd-harness sync");
+    if (r.mcp === "ja-declarado") {
+        console.log("\nmantido .mcp.json — o servidor dd-harness já está declarado");
+        return;
+    }
+    console.log("\nOpcional: as memórias como ferramenta, para o agente buscar e gravar sem" +
+        "\nescrever arquivo. Acrescente ao `.mcp.json` da raiz (não escrevo nele: o" +
+        "\narquivo é seu e pode declarar outros servidores):\n");
+    console.log(SUGESTAO_MCP);
 }
+/**
+ * Nao exige `.dd-harness.json`, e isso importa: sem projeto no servico o `init` nao tem o
+ * que apontar, criar projeto exige credencial, e credencial exigindo config fechava um
+ * ciclo sem entrada — no dia um de um repositorio novo, nenhum dos tres rodava. O `--api`
+ * resolve; com config no repo, ela preenche.
+ */
 async function comandoLogin(argv) {
     const token = argumento(argv, "token");
     if (!token)
-        throw new Error("uso: dd-harness login --token <token>");
-    const config = await leConfigDoRepo(process.cwd());
-    const caminho = await guardaToken(config.api, token);
-    console.log(`credencial de ${config.api} guardada em ${caminho}`);
+        throw new Error("uso: dd-harness login --token <token> [--api <url>]");
+    const daLinha = argumento(argv, "api");
+    const doRepo = daLinha ? null : await leConfigDoRepo(process.cwd()).catch(() => null);
+    const api = (daLinha ?? doRepo?.api ?? "https://dd-harness.vercel.app").replace(/\/$/, "");
+    const caminho = await guardaToken(api, token);
+    console.log(`credencial de ${api} guardada em ${caminho}`);
 }
 async function comandoEditar(argv) {
     const caminho = argv[0];
@@ -173,8 +193,11 @@ async function comandoSync() {
             "parei sem escrever nada: estes arquivos foram editados à mão.",
             ...resultado.arquivos.map((a) => `  ${a}`),
             "",
-            "O disco é projeção do serviço, uma direção só. Leve a mudança para o serviço,",
-            "ou descarte a edição local (git checkout / apague o arquivo) e sincronize de novo.",
+            "O disco é projeção do serviço, uma direção só. Duas saídas:",
+            "",
+            "  1. Leve a edição para o serviço — `dd-harness editar <arquivo>` para cada um",
+            "     acima. É o caminho normal de corrigir memória, e destrava o sync.",
+            "  2. Descarte a edição local (git checkout / apague o arquivo) e sincronize.",
         ].join("\n"));
         process.exitCode = 1;
         return;
@@ -240,10 +263,24 @@ async function comandoCheck(argv) {
 }
 async function comandoStatus() {
     const r = await status(process.cwd());
+    // O acervo vem primeiro, e sempre: e a resposta para "o que ha no Brain deste projeto?",
+    // que era a pergunta sem comando. Sem ela, quem quer saber conta arquivo em disco — e
+    // acerta por acidente, porque memoria arquivada sai do disco e continua no indice.
+    const { ativas, arquivadas, porPasta } = r.acervo;
+    if (ativas === 0 && arquivadas === 0) {
+        console.log("dd-harness: o Brain deste projeto está vazio.");
+    }
+    else {
+        const detalhe = porPasta.map((p) => `${p.pasta} ${p.quantas}`).join(", ");
+        console.log(`dd-harness: ${ativas} memória(s) ativa(s)` +
+            (arquivadas ? ` e ${arquivadas} arquivada(s)` : "") +
+            (detalhe ? ` — ${detalhe}` : ""));
+    }
     if (!r.comDeriva.length && !r.vencidas.length) {
-        console.log("dd-harness: nada esperando julgamento.");
+        console.log("Nada esperando julgamento.");
         return;
     }
+    console.log("");
     if (r.comDeriva.length) {
         const total = r.comDeriva.reduce((soma, m) => soma + m.abertas, 0);
         console.log(`dd-harness: ${total} deriva(s) aberta(s), esperando julgamento:`);
@@ -258,6 +295,25 @@ async function comandoStatus() {
             console.log(`  ${m.pasta}/${m.memoria} — ${m.titulo}`);
     }
 }
+/**
+ * Vem ANTES do `init`, e nao depois: o `init` escreve o `.dd-harness.json` apontando para
+ * um projeto, e apontar para projeto que nao existe deixaria todo comando seguinte em 404.
+ */
+async function comandoProjeto(argv) {
+    const slug = argv[0];
+    const nome = argumento(argv, "nome");
+    if (!slug || slug.startsWith("-") || !nome) {
+        throw new Error('uso: dd-harness projeto <slug> --nome "<nome>" [--tenant <slug>] [--api <url>]');
+    }
+    const r = await criaProjeto(process.cwd(), slug, nome, {
+        tenant: argumento(argv, "tenant"),
+        api: argumento(argv, "api"),
+    });
+    console.log(r.jaExistia
+        ? `projeto ${r.projeto} já existia — nada criado.`
+        : `criado  projeto ${r.projeto}.`);
+    console.log(`Agora: dd-harness init --tenant <espaço> --projeto ${r.projeto}`);
+}
 async function comandoPasta(argv) {
     const slug = argv[0];
     const definicao = argumento(argv, "definicao");
@@ -292,6 +348,8 @@ async function principal() {
             return comandoInit(resto);
         case "login":
             return comandoLogin(resto);
+        case "projeto":
+            return comandoProjeto(resto);
         case "pasta":
             return comandoPasta(resto);
         case "gravar":

package/dist/init.d.ts

@@ -0,0 +1,18 @@
+export type ResultadoDoInit = {
+    config: "criada" | "ja-existia";
+    claudeMd: "criado" | "linha-acrescentada" | "ja-tinha-a-linha";
+    mcp: "ja-declarado" | "a-declarar";
+};
+/**
+ * O `.mcp.json` e sugerido, nunca escrito.
+ *
+ * Pelo mesmo motivo do `CLAUDE.md` da raiz: o arquivo e do repositorio, pode ja declarar
+ * outros servidores, e mesclar JSON alheio e onde falha silenciosa nasce — entrada errada
+ * nao da erro, a ferramenta so nao aparece. Quem cola sabe o que colou.
+ */
+export declare const SUGESTAO_MCP = "{\n  \"mcpServers\": {\n    \"dd-harness\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"dd-harness-mcp\"]\n    }\n  }\n}";
+export declare function init(raiz: string, dados: {
+    tenant: string;
+    projeto: string;
+    api?: string;
+}): Promise<ResultadoDoInit>;

package/dist/init.js

@@ -10,13 +10,39 @@ import { LINHA_DE_IMPORT } from "./materializa.js";
  * acrescenta a linha ao que voce escreveu, sem tocar no resto. Adotar um projeto vira
  * uma linha, e nao um ritual de mover arquivo.
  */
-const CABECALHO = `# CLAUDE.md
-
-Este arquivo é seu: escreva aqui o que for específico deste repositório.
-
-A linha abaixo importa a política gerenciada pelo dd-harness. **Não a remova** — sem
-ela a sessão abre sem protocolo, e nada avisa.
+const CABECALHO = `# CLAUDE.md
+
+Este arquivo é seu: escreva aqui o que for específico deste repositório.
+
+A linha abaixo importa a política gerenciada pelo dd-harness. **Não a remova** — sem
+ela a sessão abre sem protocolo, e nada avisa.
 `;
+/**
+ * O `.mcp.json` e sugerido, nunca escrito.
+ *
+ * Pelo mesmo motivo do `CLAUDE.md` da raiz: o arquivo e do repositorio, pode ja declarar
+ * outros servidores, e mesclar JSON alheio e onde falha silenciosa nasce — entrada errada
+ * nao da erro, a ferramenta so nao aparece. Quem cola sabe o que colou.
+ */
+export const SUGESTAO_MCP = `{
+  "mcpServers": {
+    "dd-harness": {
+      "command": "npx",
+      "args": ["-y", "dd-harness-mcp"]
+    }
+  }
+}`;
+async function declaraMcp(raiz) {
+    try {
+        const cru = await readFile(join(raiz, ".mcp.json"), "utf8");
+        const lido = JSON.parse(cru);
+        return lido.mcpServers?.["dd-harness"] ? "ja-declarado" : "a-declarar";
+    }
+    catch {
+        // Sem arquivo, ou JSON que nao interpreta: nos dois casos ha o que sugerir.
+        return "a-declarar";
+    }
+}
 export async function init(raiz, dados) {
     const caminhoConfig = join(raiz, CAMINHO_CONFIG);
     let config = "ja-existia";
@@ -54,5 +80,5 @@ export async function init(raiz, dados) {
         await writeFile(caminhoClaude, `${atual}${separador}${LINHA_DE_IMPORT}\n`, "utf8");
         claudeMd = "linha-acrescentada";
     }
-    return { config, claudeMd };
+    return { config, claudeMd, mcp: await declaraMcp(raiz) };
 }

package/dist/materializa.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Do payload do contrato para arquivos em disco.
+ *
+ * Funcao pura de proposito: recebe o Brain e devolve caminho -> conteudo, sem rede e sem
+ * `fs`. E a parte que precisa de teste — o formato tem que casar com o que o
+ * `validate_brain.cjs` do molde espera (frontmatter `name` igual ao arquivo, `pasta`
+ * igual a pasta que o contem, e uma linha de indice por memoria).
+ */
+export type Ancora = {
+    tipo: string;
+    valor: string;
+    sha: string | null;
+};
+export type Memoria = {
+    pasta: string;
+    slug: string;
+    titulo: string;
+    resumo: string;
+    corpo: string;
+    status: "ativa" | "historico";
+    dano: string;
+    invisibilidade: string;
+    externalidade: string;
+    ancoras: Ancora[];
+    revisar_ate: string | null;
+    /** Observacoes de deriva esperando julgamento. Ausente em payload antigo. */
+    deriva_aberta?: number;
+};
+export type Brain = {
+    tenant: {
+        slug: string;
+        nome: string;
+    };
+    projeto: {
+        slug: string;
+        nome: string;
+    };
+    /** `CLAUDE.md`. Nulo ou vazio: ainda nao existe, e nao vira arquivo. */
+    politica?: string | null;
+    /** `BRIEFING.md`. Mesma regra. */
+    briefing?: string | null;
+    pastas: {
+        slug: string;
+        definicao: string;
+    }[];
+    memorias: Memoria[];
+};
+export declare function arquivoDaMemoria(m: Memoria): string;
+export declare function arquivoDoIndice(brain: Brain): string;
+/** Tudo o que o servico gera vive aqui — e nada fora daqui e escrito pelo `sync`. */
+export declare const PASTA = "dd-harness";
+/** O que a raiz precisa conter para a politica chegar a sessao. */
+export declare const LINHA_DE_IMPORT = "@dd-harness/politica.md";
+/**
+ * Caminho relativo (POSIX) -> conteúdo. As chaves são o que o manifesto guarda.
+ *
+ * Tudo dentro de `dd-harness/`, inclusive a política. Na raiz fica só o `CLAUDE.md`, que
+ * é **seu**: o `sync` não o escreve, apenas confere que ele importa a política. É o que
+ * deixa conviverem a parte gerenciada e o que aquele repositório tem de próprio — e o
+ * que faz adotar um projeto existente ser uma linha, não um ritual.
+ *
+ * Artefato vazio ou ausente não entra no mapa; como o manifesto remove o que saiu do
+ * conjunto, esvaziar no serviço apaga o arquivo no próximo `sync`.
+ */
+export declare function materializa(brain: Brain, pasta?: string): Map<string, string>;

package/dist/materializa.js

@@ -28,9 +28,14 @@ function secaoDeFiltros(m) {
     ].join("\n");
 }
 export function arquivoDaMemoria(m) {
+    // `titulo` vai no frontmatter porque `gravar` e `editar` o exigem la: sem ele o arquivo
+    // materializado nao volta pelo `editar`, e o ciclo "sincroniza, corrige, manda de volta"
+    // — que e como o agente cura memoria — para com "frontmatter sem `titulo`". O titulo
+    // tambem aparece no indice, mas indice nao e o que se edita.
     const frontmatter = [
         "---",
         `name: ${m.slug}`,
+        `titulo: ${m.titulo.replace(/\n/g, " ")}`,
         `description: ${m.resumo.replace(/\n/g, " ")}`,
         `pasta: ${m.pasta}`,
         ...(m.revisar_ate ? [`revisar-ate: ${m.revisar_ate.slice(0, 10)}`] : []),

package/dist/medir.d.ts

@@ -0,0 +1 @@
+export declare function mede(raiz: string, valor: string): Promise<string | null>;

package/dist/medir.js

@@ -32,7 +32,48 @@ async function hashDeDiretorio(caminho) {
     await anda(caminho, "");
     return createHash("sha256").update(nomes.sort().join("\n")).digest("hex");
 }
+/**
+ * Trecho: `caminho#alvo` — hash das LINHAS que contem `alvo`, nao do arquivo.
+ *
+ * Existe porque ancora de arquivo mede grosso demais. Medido: renomear a variavel de um
+ * laco disparou as 5 memorias ancoradas naquele arquivo, nenhuma delas desatualizada. Cada
+ * uma falava de um trecho diferente, e o hash do arquivo nao distingue.
+ *
+ * `null` quando o alvo nao aparece mais: e o mesmo sinal de "arquivo ausente" — o trecho que
+ * a memoria descreve deixou de existir, e o servico decide o que isso significa. Trecho que
+ * some por rename e deriva legitima, nao falso positivo: a memoria aponta para algo que
+ * nao esta mais la.
+ *
+ * Comparacao literal, sem regex: o alvo vem de quem escreveu a memoria, e regex daria
+ * poder de travar o `check` (catastrophic backtracking) a quem so queria apontar uma linha.
+ */
+async function hashDeTrecho(caminho, alvo) {
+    const conteudo = await readFile(caminho, "utf8");
+    const casam = conteudo
+        .split(/\r?\n/)
+        .filter((linha) => linha.includes(alvo))
+        .map((linha) => linha.trim());
+    if (casam.length === 0)
+        return null;
+    return createHash("sha256").update(casam.join("\n"), "utf8").digest("hex");
+}
 export async function mede(raiz, valor) {
+    // O `#` separa alvo de caminho. O CHECK do banco garante um so, e nenhum lado vazio.
+    const corte = valor.indexOf("#");
+    if (corte !== -1) {
+        const caminho = join(raiz, valor.slice(0, corte));
+        const alvo = valor.slice(corte + 1);
+        try {
+            const info = await stat(caminho);
+            // Trecho de diretorio nao existe: o alvo e texto dentro de um arquivo.
+            if (info.isDirectory())
+                return null;
+            return await hashDeTrecho(caminho, alvo);
+        }
+        catch {
+            return null;
+        }
+    }
     const caminho = join(raiz, valor);
     try {
         const info = await stat(caminho);

package/dist/pasta.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `dd-harness pasta <slug> --definicao "..."` — cria a pasta sem sair da sessao.
+ *
+ * `gravar` recusa quando a pasta nao existe, e essa recusa e boa: e ela que impede um
+ * typo no `pasta:` de virar pasta nova em silencio. O que faltava era a saida — ate aqui
+ * o agente parava e pedia que alguem abrisse o navegador.
+ */
+export declare function criaPasta(raiz: string, slug: string, definicao: string): Promise<{
+    pasta: string;
+    jaExistia: boolean;
+}>;

package/dist/pasta.js

@@ -1,4 +1,4 @@
-import { leConfigDoRepo, leToken } from "./config.js";
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
 /**
  * `dd-harness pasta <slug> --definicao "..."` — cria a pasta sem sair da sessao.
  *
@@ -7,14 +7,10 @@ import { leConfigDoRepo, leToken } from "./config.js";
  * o agente parava e pedia que alguem abrisse o navegador.
  */
 export async function criaPasta(raiz, slug, definicao) {
-    const config = await leConfigDoRepo(raiz);
-    const token = await leToken(config.api);
-    if (!token) {
-        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
-    }
-    const resposta = await fetch(`${config.api}/api/v1/pastas`, {
+    const { config, token } = await credencial(raiz);
+    const resposta = await pede(`${config.api}/api/v1/pastas`, {
         method: "POST",
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        headers: cabecalhos(token, true),
         body: JSON.stringify({
             tenant: config.tenant,
             projeto: config.projeto,
@@ -27,10 +23,8 @@ export async function criaPasta(raiz, slug, definicao) {
     // nao criou nada.
     if (resposta.status === 409)
         return { pasta: slug, jaExistia: true };
-    if (!resposta.ok) {
-        const { erro } = (await resposta.json().catch(() => ({})));
-        throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
-    }
+    if (!resposta.ok)
+        await recusa(resposta);
     const { pasta } = (await resposta.json());
     return { pasta, jaExistia: false };
 }

package/dist/projeto.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `dd-harness projeto <slug> --nome "..."` — cria o projeto sem sair da sessao.
+ *
+ * Era o ultimo passo do espaco que exigia navegador. O tenant continua manual de
+ * proposito (fronteira de isolamento e ato de dono), mas daqui para baixo o agente que
+ * abre um repositorio novo consegue preparar tudo: projeto, pasta e memoria.
+ *
+ * Nao escreve o `.dd-harness.json`: quem faz isso e o `init`, e ele precisa de um projeto
+ * que ja exista. A ordem e `projeto` e depois `init` — e por isso este comando NAO pode
+ * exigir o config do repo, que nesse momento ainda nao existe. Daí `--tenant` e `--api`:
+ * sem config, eles vem da linha de comando; com config, ele preenche o que faltar.
+ */
+export declare function criaProjeto(raiz: string, slug: string, nome: string, explicito?: {
+    tenant?: string;
+    api?: string;
+}): Promise<{
+    projeto: string;
+    jaExistia: boolean;
+}>;

package/dist/projeto.js

@@ -0,0 +1,39 @@
+import { cabecalhos, pede, recusa } from "./api.js";
+import { leConfigDoRepo, leToken } from "./config.js";
+/**
+ * `dd-harness projeto <slug> --nome "..."` — cria o projeto sem sair da sessao.
+ *
+ * Era o ultimo passo do espaco que exigia navegador. O tenant continua manual de
+ * proposito (fronteira de isolamento e ato de dono), mas daqui para baixo o agente que
+ * abre um repositorio novo consegue preparar tudo: projeto, pasta e memoria.
+ *
+ * Nao escreve o `.dd-harness.json`: quem faz isso e o `init`, e ele precisa de um projeto
+ * que ja exista. A ordem e `projeto` e depois `init` — e por isso este comando NAO pode
+ * exigir o config do repo, que nesse momento ainda nao existe. Daí `--tenant` e `--api`:
+ * sem config, eles vem da linha de comando; com config, ele preenche o que faltar.
+ */
+export async function criaProjeto(raiz, slug, nome, explicito = {}) {
+    const doRepo = await leConfigDoRepo(raiz).catch(() => null);
+    const tenant = explicito.tenant ?? doRepo?.tenant;
+    const api = (explicito.api ?? doRepo?.api ?? "https://dd-harness.vercel.app").replace(/\/$/, "");
+    if (!tenant) {
+        throw new Error("não sei em que espaço criar: passe `--tenant <slug>` (ou rode dentro de um repositório já com .dd-harness.json).");
+    }
+    const token = await leToken(api);
+    if (!token) {
+        throw new Error(`sem credencial para ${api}. Rode \`dd-harness login --token <token>\`.`);
+    }
+    const resposta = await pede(`${api}/api/v1/projetos`, {
+        method: "POST",
+        headers: cabecalhos(token, true),
+        body: JSON.stringify({ tenant, slug, nome }),
+    });
+    // Como em `pasta`: projeto que ja existe nao e falha para quem chamou, o estado desejado
+    // ja vale. Vale dizer que existia — quem pediu pode estar corrigindo um typo.
+    if (resposta.status === 409)
+        return { projeto: slug, jaExistia: true };
+    if (!resposta.ok)
+        await recusa(resposta);
+    const { projeto } = (await resposta.json());
+    return { projeto, jaExistia: false };
+}

package/dist/sync.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Busca o Brain e escreve em disco. Uma direcao so.
+ *
+ * O manifesto guarda o hash de cada arquivo que este comando escreveu. Antes de
+ * sobrescrever, ele confere: hash igual ao guardado significa "isto e meu, posso
+ * reescrever"; hash diferente significa que alguem editou a mao, e ai o comando **para**.
+ * Deriva silenciosa entre repo e servico e exatamente o que este projeto existe para
+ * evitar — melhor falhar alto do que engolir a edicao de alguem.
+ */
+/**
+ * Estado do ponteiro na raiz.
+ *
+ * `CLAUDE.md` nao e gerado — e do repositorio, e so precisa importar a politica. Mas o
+ * import falha em **silencio**: sem o arquivo alvo, ou sem a linha, a sessao abre e
+ * nada avisa que a politica nao veio junto. Foi medido, nao suposto. Como a sessao sem
+ * protocolo e a falha que o molde mais combate, o `sync` confere isso toda vez — mesmo
+ * quando o servico nao mudou, porque quem apaga a linha e quem mexe no repositorio.
+ */
+export type Ponteiro = "ok" | "sem-claude-md" | "sem-a-linha" | "sem-politica"
+/**
+ * A linha de import existe, mas nao ha politica no servico para ela apontar. O `init`
+ * escreve a linha antes de existir politica, entao o repositorio novo cai aqui: import
+ * pendurado desde o primeiro dia, e o mesmo silencio de sempre.
+ */
+ | "aponta-para-o-vazio";
+type Resultado = {
+    ponteiro: Ponteiro;
+} & ({
+    tipo: "sem-mudanca";
+} | {
+    tipo: "sincronizado";
+    escritos: string[];
+    removidos: string[];
+} | {
+    tipo: "editado-a-mao";
+    arquivos: string[];
+});
+/**
+ * Estado do que este comando escreveu, contra o hash guardado.
+ *
+ * Duas situacoes diferentes, e confundi-las custa caro: hash diferente e **edicao a
+ * mao**, e o comando tem que parar sem escrever; arquivo **ausente** nao e edicao — e
+ * trabalho a refazer, e o comando tem que reescrever.
+ */
+export declare function confereDisco(raiz: string, arquivos: Record<string, string>): Promise<{
+    editados: string[];
+    faltando: string[];
+}>;
+/**
+ * O `CLAUDE.md` da raiz existe e importa a politica?
+ *
+ * Sem politica no servico E sem a linha, nao ha o que apontar nem o que avisar — avisar
+ * ai seria ruido que ensina a ignorar aviso. Mas com a linha escrita e a politica vazia o
+ * import esta pendurado de verdade, e esse e o silencio que a memoria
+ * `import-do-claude-md-falha-calado` manda quebrar.
+ */
+export declare function confereOPonteiro(raiz: string, temPolitica: boolean): Promise<Ponteiro>;
+export declare function sync(raiz: string): Promise<Resultado>;
+export {};

package/dist/sync.js

@@ -1,4 +1,5 @@
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { pede } from "./api.js";
 import { dirname, join } from "node:path";
 import { gravaManifesto, hashDe, leConfigDoRepo, leManifesto, leToken, } from "./config.js";
 import { LINHA_DE_IMPORT, materializa } from "./materializa.js";
@@ -31,7 +32,7 @@ export async function confereDisco(raiz, arquivos) {
 }
 async function buscaBrain(config, token, etag) {
     const url = `${config.api}/api/v1/artefatos?tenant=${encodeURIComponent(config.tenant)}&projeto=${encodeURIComponent(config.projeto)}`;
-    const resposta = await fetch(url, {
+    const resposta = await pede(url, {
         headers: {
             Authorization: `Bearer ${token}`,
             ...(etag ? { "If-None-Match": etag } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dd-harness",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "type": "module",
   "description": "Materializa politica, briefing e Brain do dd-harness no repositorio. Sem dependencia: fetch, crypto e fs sao do Node.",
   "license": "UNLICENSED",
@@ -21,6 +21,15 @@
   "bin": {
     "dd-harness": "dist/index.js"
   },
+  "//exports": "Aponta para `dist` porque quem IMPORTA isto em tempo de execucao e o Node, que nao executa TypeScript. Nao aponte para `src`: o Node segue os imports relativos de dentro do arquivo e tenta abrir `./api.js` ao lado do `.ts`, que nao existe. Quem consome no workspace e o `packages/mcp`, e ele compila o fonte do CLI junto (ver o tsconfig.build.json dele) em vez de depender deste campo — assim o build funciona num checkout limpo, sem `dist` previo.",
+  "exports": {
+    "./api": "./dist/api.js",
+    "./buscar": "./dist/buscar.js",
+    "./curar": "./dist/curar.js",
+    "./gravar": "./dist/gravar.js",
+    "./pasta": "./dist/pasta.js",
+    "./projeto": "./dist/projeto.js"
+  },
   "files": [
     "dist"
   ],