agent-devkit 0.2.0 → 0.3.0

package/README.md

@@ -2,6 +2,9 @@
 
 Agent DevKit is a CLI runtime for specialist AI agents, capabilities,
 provider-aware automations and local host adapters for Codex and Claude.
+On first run, the npm wrapper creates a local Python environment under
+`~/.agent-devkit/python` (or `AGENT_DEVKIT_HOME`) and installs the bundled
+`requirements.txt` dependencies.
 
 The npm package installs the canonical command:
 
@@ -18,6 +21,7 @@ npm install -g agent-devkit
 Validate the installation:
 
 ```bash
+agent
 agent --version
 agent -v
 agent doctor
@@ -26,7 +30,7 @@ agent doctor
 Expected version for this release:
 
 ```text
-agent 0.2.0
+agent 0.3.0
 ```
 
 ## Quick Start
@@ -41,12 +45,13 @@ agent llm list
 agent commands list
 ```
 
-Agent DevKit `v0.2.0` also includes deterministic runtime discovery and
+Agent DevKit `v0.3.0` also includes deterministic runtime discovery and
 integration commands:
 
 ```bash
 agent roadmap
 agent catalog search pr
+agent plan "review this Azure card"
 agent route explain "review the PRs waiting for me"
 agent eval run routing
 agent secrets doctor
@@ -72,6 +77,43 @@ Natural-language mode requires an LLM backend. Deterministic commands such as
 `agent agents list`, `agent capabilities list`, `agent doctor`, `agent provider`
 and `agent run` do not require an LLM.
 
+Running `agent` without arguments starts the local onboarding status and wizard:
+memory, personality, LLM backends, Ollama, toolchain, sources and next actions.
+Use `agent onboard minimal` for identity, coordinator LLM, Qwen3-0.6B via
+Ollama and local memory. Use `agent onboard complete` to include toolchain,
+providers/sources, specialist catalog, local automations, tasks, notifications,
+knowledge and shared memory. Both commands return plans; external installs
+still require explicit opt-in.
+
+The canonical executable remains `agent`, but the local public agent name can be
+changed during onboarding, with `agent --rename <name>`, with
+`agent personality edit --rename <name>`, or through a natural-language prompt
+such as `agent "mude seu nome para ianota10"`. To expose an executable alias,
+use `agent alias add <name>`.
+
+Useful operational commands:
+
+```bash
+agent plan "analyze Azure card 7914"
+agent execute --dry-run "summarize these logs"
+agent workflow install daily-pr-review --dry-run
+agent local-llm doctor
+agent local-llm install qwen3:0.6b --dry-run
+agent skill create my-skill --description "Local skill"
+agent script create hello --command "echo hello"
+agent team init
+agent team doctor
+agent knowledge init
+agent knowledge search "runbook procedure"
+agent shared-memory create --title "Support runbooks"
+agent shared-memory submit <memory-id> --title "New runbook" --content "..." --key <contributor-key>
+agent shared-memory review <memory-id> <submission-id>
+agent shared-memory publish <memory-id> <submission-id> --yes --owner-key <owner-key>
+agent contribute pr my-extension --dry-run
+agent mcp manifest
+agent mcp serve
+```
+
 ## Complete Configuration Tutorial
 
 There are three practical ways to use agents from the CLI:
@@ -187,10 +229,10 @@ agent llm doctor openrouter
 ```bash
 agent ollama status
 agent ollama models
-agent ollama pull qwen2.5-coder --dry-run
-agent ollama pull qwen2.5-coder --yes
+agent ollama pull qwen3:0.6b --dry-run
+agent ollama pull qwen3:0.6b --yes
 ollama serve
-agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen2.5-coder --set-default
+agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen3:0.6b --set-default
 agent llm doctor ollama
 ```
 
@@ -304,7 +346,7 @@ agent llm configure openrouter --api-key-env OPENROUTER_API_KEY --model openai/g
 Local or host-authenticated backends:
 
 ```bash
-agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen2.5-coder --set-default
+agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen3:0.6b --set-default
 agent llm configure codex-cli --set-default
 agent llm configure claude-code --set-default
 ```

package/bin/agent.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
-import { accessSync, constants } from "node:fs";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -9,6 +10,8 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, "..");
 const runtimeRoot = path.join(packageRoot, "runtime");
 const runtimeAgent = path.join(runtimeRoot, "agent");
+const runtimeRequirements = path.join(runtimeRoot, "requirements.txt");
+const packageJson = JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8"));
 
 function canExecute(command) {
   const result = spawnSync(command, ["--version"], {
@@ -22,13 +25,130 @@ function resolvePython() {
   if (process.env.AGENT_DEVKIT_PYTHON) {
     return process.env.AGENT_DEVKIT_PYTHON;
   }
-  if (canExecute("python3")) {
-    return "python3";
+  const basePython = canExecute("python3") ? "python3" : (canExecute("python") ? "python" : null);
+  if (!basePython) {
+    return null;
   }
-  if (canExecute("python")) {
-    return "python";
+  if (!existsSync(runtimeRequirements)) {
+    return basePython;
+  }
+  return ensureBundledPython(basePython);
+}
+
+function resolveAppHome() {
+  if (process.env.AGENT_DEVKIT_HOME) return process.env.AGENT_DEVKIT_HOME;
+  if (process.env.AI_DEVKIT_CONFIG_HOME) return process.env.AI_DEVKIT_CONFIG_HOME;
+  if (process.env.AIKIT_CONFIG_HOME) return process.env.AIKIT_CONFIG_HOME;
+  return path.join(os.homedir(), ".agent-devkit");
+}
+
+function venvPythonPath(venvRoot) {
+  if (process.platform === "win32") {
+    return path.join(venvRoot, "Scripts", "python.exe");
+  }
+  return path.join(venvRoot, "bin", "python");
+}
+
+function runOrFail(command, args, message, options = {}) {
+  const result = spawnSync(command, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: false,
+    text: true,
+    ...options,
+  });
+  if (result.status === 0) {
+    return result;
+  }
+  const details = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+  throw new Error(`${message}${details ? `\n${details}` : ""}`);
+}
+
+function commandOk(command, args) {
+  const result = spawnSync(command, args, {
+    stdio: "ignore",
+    shell: false,
+  });
+  return result.status === 0;
+}
+
+function canAutoInstallPythonVenv() {
+  return (
+    process.platform === "linux"
+    && typeof process.getuid === "function"
+    && process.getuid() === 0
+    && process.env.AGENT_DEVKIT_DISABLE_SYSTEM_BOOTSTRAP !== "1"
+    && canExecute("apt-get")
+  );
+}
+
+function tryInstallPythonVenvPackage() {
+  if (!canAutoInstallPythonVenv()) {
+    return false;
+  }
+  if (!commandOk("apt-get", ["update"])) {
+    return false;
+  }
+  return commandOk("apt-get", ["install", "-y", "python3-venv"]);
+}
+
+function createVenv(basePython, venvRoot) {
+  const result = spawnSync(basePython, ["-m", "venv", venvRoot], {
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: false,
+    text: true,
+  });
+  if (result.status === 0) {
+    return;
+  }
+  if (tryInstallPythonVenvPackage()) {
+    runOrFail(basePython, ["-m", "venv", venvRoot], "Failed to create Agent DevKit Python environment.");
+    return;
+  }
+  const details = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+  throw new Error(`Failed to create Agent DevKit Python environment.${details ? `\n${details}` : ""}`);
+}
+
+function pythonImportsOk(python) {
+  const result = spawnSync(
+    python,
+    ["-c", "import yaml, jsonschema, bs4, pypdf, reportlab"],
+    { stdio: "ignore", shell: false },
+  );
+  return result.status === 0;
+}
+
+function ensureBundledPython(basePython) {
+  const appHome = resolveAppHome();
+  const venvRoot = process.env.AGENT_DEVKIT_PYTHON_ENV || path.join(appHome, "python");
+  const python = venvPythonPath(venvRoot);
+  const marker = path.join(venvRoot, ".agent-devkit-deps.json");
+  mkdirSync(appHome, { recursive: true });
+
+  if (!existsSync(python)) {
+    createVenv(basePython, venvRoot);
+  }
+  if (pythonImportsOk(python) && markerMatches(marker)) {
+    return python;
+  }
+  runOrFail(
+    python,
+    ["-m", "pip", "install", "--upgrade", "pip", "-r", runtimeRequirements],
+    "Failed to install Agent DevKit Python dependencies.",
+  );
+  writeFileSync(marker, JSON.stringify({ version: packageJson.version, requirements: "runtime/requirements.txt" }, null, 2));
+  return python;
+}
+
+function markerMatches(marker) {
+  if (!existsSync(marker)) {
+    return false;
+  }
+  try {
+    const payload = JSON.parse(readFileSync(marker, "utf8"));
+    return payload.version === packageJson.version;
+  } catch {
+    return false;
   }
-  return null;
 }
 
 try {
@@ -38,7 +158,13 @@ try {
   process.exit(1);
 }
 
-const python = resolvePython();
+let python = null;
+try {
+  python = resolvePython();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : "Agent DevKit Python bootstrap failed.");
+  process.exit(1);
+}
 if (!python) {
   console.error("Agent DevKit requires Python 3.11+ available as python3 or python.");
   console.error("Set AGENT_DEVKIT_PYTHON to a Python executable if it is installed in a custom location.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-devkit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Agent DevKit CLI runtime for specialist AI agents, capabilities and provider-aware automations.",
   "type": "module",
   "license": "MIT",

package/runtime/README.md

@@ -22,13 +22,19 @@ npm install -g agent-devkit
 Valide a instalacao:
 
 ```bash
+agent
 agent --version
 agent -v
 agent doctor
 ```
 
 O pacote instala o comando canonico `agent`. O nome do pacote npm e
-`agent-devkit`.
+`agent-devkit`. Na primeira execucao, o wrapper npm prepara um ambiente Python
+local em `~/.agent-devkit/python` (ou no `AGENT_DEVKIT_HOME`) e instala as
+dependencias de `requirements.txt`, para evitar setup manual de bibliotecas
+Python. Ao executar apenas `agent`, o CLI entra no onboarding local: verifica
+memoria, personalidade, backends LLM, Ollama, toolchain, sources, tasks e
+proximas acoes sem exigir prompt manual.
 
 ## Primeiro uso
 
@@ -44,18 +50,27 @@ agent commands list
 agent doctor
 ```
 
-Na `v0.2.0`, o runtime tambem expoe superficies deterministicas para
+Na `v0.3.0`, o runtime tambem expoe superficies deterministicas para
 descoberta, avaliacao e integracao por hosts:
 
 ```bash
+agent onboard minimal
+agent onboard complete
 agent roadmap
 agent catalog search pr
+agent plan "analise o card 7914 do azure"
 agent route explain "revise as prs que recebi hoje"
 agent eval run routing
 agent secrets doctor
 agent mcp tools
 ```
 
+`agent onboard minimal` planeja o setup essencial: identidade, coordenador LLM,
+mini-cerebro Qwen3-0.6B via Ollama e memoria local. `agent onboard complete`
+inclui tambem toolchain, providers/sources, catalogo de agentes, automacoes
+locais, tarefas, notificacoes, knowledge e memoria compartilhada. Ambos
+retornam plano deterministico; instalacoes externas continuam exigindo opt-in.
+
 Instale os artefatos locais do Agent DevKit no projeto em que voce trabalha:
 
 ```bash
@@ -78,6 +93,24 @@ Esse modo usa backend LLM. Se nenhum backend estiver configurado, a CLI informa
 como configurar uma LLM ou como executar uma capability deterministica com
 `agent run`.
 
+O nome publico do agente e configuravel localmente sem mudar o comando
+canonico. O comando continua sendo `agent`, mas a identidade pode ser alterada
+no onboarding, por flag ou por linguagem natural:
+
+```bash
+agent --rename Ianota
+agent personality edit --rename Ianota
+agent "mude seu nome para ianota10"
+agent "qual seu nome?"
+```
+
+Se voce quiser tambem chamar o executavel por outro nome, crie um alias local:
+
+```bash
+agent alias add jarvis
+~/.agent-devkit/bin/jarvis "qual seu nome?"
+```
+
 ## Tutorial completo de configuracao
 
 Existem tres formas principais de usar agentes pelo CLI:
@@ -224,10 +257,10 @@ final.
 ```bash
 agent ollama status
 agent ollama models
-agent ollama pull qwen2.5-coder --dry-run
-agent ollama pull qwen2.5-coder --yes
+agent ollama pull qwen3:0.6b --dry-run
+agent ollama pull qwen3:0.6b --yes
 ollama serve
-agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen2.5-coder --set-default
+agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen3:0.6b --set-default
 agent llm doctor ollama
 ```
 
@@ -270,6 +303,11 @@ Existem dois modos de execucao:
 - `agent "<prompt>"`: entrada em linguagem natural; monta um plano multiagente,
   usa capabilities deterministicas quando possivel e exige backend LLM apenas
   quando nenhuma rota local atende a tarefa.
+- `agent plan "<prompt>"`: gera o plano multiagente explicito sem executar LLM,
+  automacao ou escrita externa.
+- `agent execute "<prompt>"` e `agent orchestrate "<prompt>"`: executam pelo
+  runtime agentico com roteamento, wizard de provider/source, modelo local
+  quando permitido e review gate.
 - `agent run <agent> <capability>`: execucao deterministica; nao exige LLM.
 
 Exemplo em linguagem natural:
@@ -309,6 +347,123 @@ saidas:
 agent inspect azure-devops-orchestrator read-card
 ```
 
+Comandos operacionais da `v0.2.1`:
+
+```bash
+agent catalog list --type workflow
+agent catalog rebuild-index
+agent workflow show daily-pr-review
+agent workflow install daily-pr-review --dry-run
+agent local-llm doctor
+agent local-llm install qwen3:0.6b --dry-run
+agent skill create minha-skill --description "Skill local"
+agent script create hello --command "echo hello"
+agent agents create meu-agente --description "Agente local"
+agent team init
+agent team doctor
+agent contribute pr minha-extensao --dry-run
+```
+
+O MCP stdio embutido fica disponivel sempre que o CLI esta instalado:
+
+```bash
+agent mcp manifest
+agent mcp tools
+agent mcp serve
+```
+
+As ferramentas MCP expõem catalogo, onboarding, doctor, route explain, plano
+agentico, evals, workflows, LLM local, artefatos locais, sources, wizards,
+memoria local e memoria compartilhada. As operacoes com risco de escrita
+externa continuam bloqueadas ou em dry-run por padrao.
+
+## Memoria compartilhada
+
+Memorias compartilhadas sao workspaces locais em `.agent-devkit/shared-memory`.
+O criador e o dono da memoria; outros agentes recebem uma URL local e uma chave
+de contribuidor, enviam novidades para `incoming`, e o dono revisa antes de
+publicar em `accepted`.
+
+```bash
+agent shared-memory create --title "Runbooks de suporte"
+agent shared-memory submit <memory-id> --title "Novo runbook" --content "..." --key <contributor-key>
+agent shared-memory review <memory-id> <submission-id>
+agent shared-memory publish <memory-id> <submission-id> --yes --owner-key <owner-key>
+```
+
+## Modo equipe
+
+O modo equipe cria uma configuracao versionavel de projeto em
+`.agent-devkit/team.yaml`. Esse arquivo pode guardar defaults de providers,
+sources, workflows, permissoes, limites de LLM local e politica de prompt
+injection, mas nunca valores de credenciais.
+
+```bash
+agent team init
+agent team status
+agent team doctor
+agent team onboard
+agent team profile list
+agent team profile show default
+agent team profile export default --path ./team-profile.yaml
+agent team profile import ./team-profile.yaml
+```
+
+Segredos continuam pessoais, em `~/.agent-devkit`, por referencia segura:
+
+```bash
+agent secret set azure-devops pat --env AZURE_DEVOPS_PAT
+```
+
+## Knowledge fabric local
+
+A `v0.3.0` introduz uma base de conhecimento compartilhada file-first. A fonte
+canonica e um diretorio `knowledge-base/` com Markdown, JSON e YAML; indices
+lexicais ou semanticos sao derivados e podem ser recriados.
+
+```bash
+agent knowledge init
+agent knowledge doctor
+agent knowledge snapshot create --title "Runbook" --content "# Runbook..."
+agent knowledge review runbook
+agent knowledge publish runbook --yes --owner-agent knowledge-owner
+agent knowledge snapshot list
+agent knowledge snapshot show runbook
+agent knowledge snapshot score runbook
+agent knowledge snapshot submit runbook
+agent knowledge review list
+agent knowledge curate
+agent knowledge sync
+agent knowledge reindex
+agent knowledge search "runbook procedimento"
+agent knowledge index
+agent knowledge-base create --provider github
+agent knowledge-base join kb_01JZ... --provider s3
+```
+
+Snapshots sao tratados como conteudo externo nao confiavel. A revisao bloqueia
+segredos, PII obvia e sinais de prompt injection antes de publicar localmente.
+
+Os providers `knowledge-*` documentam o storage previsto para GitHub, S3,
+Supabase Storage, Google Drive, SharePoint, OneDrive, Notion, Obsidian,
+filesystem local e indice vetorial derivado. Providers remotos ficam em
+`draft`, exigem opt-in e fallback para plano/manual enquanto nao houver
+credencial e implementacao ativa.
+
+## QA destrutivo em Docker
+
+Para validar instalacao limpa, bootstrap de dependencias, onboarding, memoria,
+knowledge-base, MCP, desinstalacao e remocao da `.agent-devkit` sem tocar no
+host:
+
+```bash
+npm run docker:qa
+```
+
+O script empacota o runtime local, instala o tarball em um container
+`node:20-bookworm`, executa os fluxos criticos e remove o home local criado no
+container.
+
 ## Configurar providers
 
 Providers tambem sao configurados por referencia. Configure apenas o que for
@@ -430,6 +585,10 @@ Comandos uteis:
 agent commands list
 agent inspect azure-devops-orchestrator read-card
 agent memory show
+agent memory backup create --title "Antes da migracao"
+export AGENT_DEVKIT_BACKUP_PASSPHRASE="frase longa"
+agent memory backup create --title "Antes da migracao" --encrypted --passphrase-env AGENT_DEVKIT_BACKUP_PASSPHRASE
+agent memory backup restore <backup-id> --yes
 agent memory reset --all
 ```
 
@@ -699,6 +858,9 @@ e ignorado pelo Git. Para Azure DevOps, `AZURE_DEVOPS_ORG` e
   rastreio de requests, padroes de erro e relatorios de logs.
 - [`execution-reviewer`](agents/execution-reviewer/): agente runtime de
   revisao final, revisao de planos e revisao de resultados antes da conclusao.
+- [`contribution-reviewer`](agents/contribution-reviewer/): agente runtime para
+  validar extensoes locais, revisar riscos de contribuicao upstream e planejar
+  PRs em modo report-only.
 - [`excel-workbook-builder`](agents/excel-workbook-builder/): especialista em
   templates, preenchimento, conciliacao, revisao e exportacao de planilhas
   Excel.
@@ -708,10 +870,27 @@ e ignorado pelo Git. Para Azure DevOps, `AZURE_DEVOPS_ORG` e
 - [`github-pr-reviewer`](agents/github-pr-reviewer/): especialista em Pull
   Requests GitHub para listar revisoes pendentes, inspecionar PRs, revisar diffs
   em modo report-only e criar automacoes locais conservadoras.
+- [`knowledge-infra-builder`](agents/knowledge-infra-builder/): especialista em
+  criar e diagnosticar a infraestrutura file-first da knowledge base
+  compartilhada.
+- [`knowledge-author`](agents/knowledge-author/): especialista em criar
+  snapshots de conhecimento reutilizavel, sanitizado e revisavel.
 - [`knowledge-generator`](agents/knowledge-generator/): especialista em gerar
   knowledge versionavel a partir de arquivos, pastas, projetos e documentacoes.
+- [`knowledge-reviewer`](agents/knowledge-reviewer/): especialista em revisar
+  snapshots, bloqueando segredo, PII indevida, duplicidade e prompt injection.
+- [`knowledge-curator`](agents/knowledge-curator/): especialista em curadoria
+  continua, deduplicacao, arquivamento e reindexacao derivada da knowledge base.
+- [`knowledge-owner`](agents/knowledge-owner/): autoridade de publicacao
+  controlada da knowledge base principal apos revisao.
 - [`local-llm-operator`](agents/local-llm-operator/): agente runtime para
   diagnosticar, selecionar e delegar tarefas operacionais a LLMs locais.
+- [`local-memory-manager`](agents/local-memory-manager/): agente runtime para
+  inspecionar e curar memoria local, preferencias, sessoes e identidade sem
+  expor segredos.
+- [`memory-sync-manager`](agents/memory-sync-manager/): especialista em
+  planejar backup, restore e sincronizacao seletiva da memoria local e
+  personalidade.
 - [`notification-operator`](agents/notification-operator/): agente runtime para
   formatar, enviar e configurar notificacoes locais de tarefas com payload
   canonico.
@@ -728,6 +907,9 @@ e ignorado pelo Git. Para Azure DevOps, `AZURE_DEVOPS_ORG` e
   especialista em inspecao local e auditoria report-only de projetos Supabase,
   cobrindo RLS, Auth, Storage, migrations, Edge Functions e planos de correcao
   sem aplicar mudancas reais.
+- [`shared-memory-curator`](agents/shared-memory-curator/): agente runtime para
+  criar memorias compartilhadas, revisar contribuicoes externas e publicar
+  apenas conteudo aprovado pelo dono.
 - [`provider-configurator`](agents/provider-configurator/): agente runtime que
   conduz wizard de providers, sources e referencias seguras de credenciais.
 - [`presentation-deck-builder`](agents/presentation-deck-builder/):

package/runtime/agent

@@ -14,11 +14,13 @@ SESSION_SHORTCUTS = {"-s", "--sessions"}
 AGENT_PROMPT_FLAGS = {"--llm", "--no-llm-fallback", "--session", "--new-session"}
 EXPLAIN_FLAGS = {"--explain"}
 GLOBAL_PROMPT_FLAGS = {"--json", "--dry-run"}
+RENAME_FLAGS = {"--rename"}
+AGENTIC_PROMPT_COMMANDS = {"plan", "execute", "orchestrate"}
 
 
 def normalize_args(argv: list[str]) -> list[str]:
     if not argv:
-        return ["agent"]
+        return ["onboard"]
     commands = set(DETERMINISTIC_COMMANDS) | set(LLM_COMMANDS)
     leading: list[str] = []
     remaining = list(argv)
@@ -26,14 +28,20 @@ def normalize_args(argv: list[str]) -> list[str]:
         leading.append(remaining.pop(0))
     if leading:
         if not remaining:
-            return [*leading, "agent"]
+            return [*leading, "onboard"]
         if remaining[0] in SESSION_SHORTCUTS:
             return [*leading, *remaining]
         if remaining[0] in EXPLAIN_FLAGS:
             return [*leading, "route", "explain", *remaining[1:]]
+        if remaining[0] in RENAME_FLAGS:
+            return [*leading, "personality", "edit", *remaining]
+        if remaining[0] in AGENTIC_PROMPT_COMMANDS:
+            prompt_flags, prompt_args = split_global_prompt_flags(remaining[1:])
+            return [*leading, remaining[0], *prompt_flags, *prompt_args]
         if remaining[0] in commands:
             return [*leading, *remaining]
-        return [*leading, "agent", *remaining]
+        prompt_flags, prompt_args = split_global_prompt_flags(remaining)
+        return [*leading, *prompt_flags, "agent", *prompt_args]
     first = remaining[0]
     if first in {"--help", "-h", "--version", "-v"}:
         return remaining
@@ -41,11 +49,29 @@ def normalize_args(argv: list[str]) -> list[str]:
         return remaining
     if first in EXPLAIN_FLAGS:
         return ["route", "explain", *remaining[1:]]
+    if first in RENAME_FLAGS:
+        return ["personality", "edit", *remaining]
     if first in AGENT_PROMPT_FLAGS:
-        return ["agent", *remaining]
+        prompt_flags, prompt_args = split_global_prompt_flags(remaining)
+        return [*prompt_flags, "agent", *prompt_args]
+    if first in AGENTIC_PROMPT_COMMANDS:
+        prompt_flags, prompt_args = split_global_prompt_flags(remaining[1:])
+        return [first, *prompt_flags, *prompt_args]
     if first in commands:
         return remaining
-    return ["agent", *remaining]
+    prompt_flags, prompt_args = split_global_prompt_flags(remaining)
+    return [*prompt_flags, "agent", *prompt_args]
+
+
+def split_global_prompt_flags(argv: list[str]) -> tuple[list[str], list[str]]:
+    leading: list[str] = []
+    remaining: list[str] = []
+    for item in argv:
+        if item in GLOBAL_PROMPT_FLAGS:
+            leading.append(item)
+        else:
+            remaining.append(item)
+    return leading, remaining
 
 
 if __name__ == "__main__":

package/runtime/agents/README.md

@@ -71,6 +71,8 @@ agents/<agent-id>/
   artefatos Docker locais sem executar build, push ou deploy real.
 - `execution-loop-builder`: especialista em planejar, gerar, revisar e
   registrar loops de execucao controlados com budgets e criterios de parada.
+- `contribution-reviewer`: agente runtime para validar extensoes locais,
+  revisar riscos de contribuicao upstream e planejar PRs em modo report-only.
 - `drawio-diagram-builder`: especialista em diagramas Draw.io editaveis a
   partir de fontes reais, entrevista, geracao, revisao e refinamento.
 - `elasticsearch-log-analyzer`: especialista em logs no Elasticsearch.
@@ -83,10 +85,24 @@ agents/<agent-id>/
 - `github-pr-reviewer`: especialista em Pull Requests GitHub, revisao
   report-only, permissao explicita para comentarios/aprovacoes e automacoes
   locais conservadoras.
+- `knowledge-infra-builder`: especialista em criar e diagnosticar a
+  infraestrutura file-first da knowledge base compartilhada.
+- `knowledge-author`: especialista em criar snapshots de conhecimento
+  reutilizavel, sanitizado e revisavel.
 - `knowledge-generator`: especialista em gerar knowledge versionavel a partir de
   fontes locais e documentacoes.
+- `knowledge-reviewer`: especialista em revisar snapshots, bloqueando segredo,
+  PII indevida, duplicidade e prompt injection.
+- `knowledge-curator`: especialista em curadoria continua, deduplicacao,
+  arquivamento e reindexacao derivada da knowledge base.
+- `knowledge-owner`: autoridade de publicacao controlada da knowledge base
+  principal apos revisao.
 - `local-llm-operator`: agente runtime para diagnosticar, selecionar e delegar
   tarefas operacionais a LLMs locais como Ollama.
+- `local-memory-manager`: agente runtime para inspecionar e curar memoria local,
+  preferencias, sessoes e identidade sem expor segredos.
+- `memory-sync-manager`: especialista em planejar backup, restore e
+  sincronizacao seletiva da memoria local e personalidade.
 - `n1-support-agent`: especialista N1 para runbooks operacionais a partir de
   cards Azure DevOps.
 - `n2-support-agent`: especialista N2 para investigacao de causa raiz e geracao
@@ -106,6 +122,8 @@ agents/<agent-id>/
   Server.
 - `sqlserver-change-operator`: especialista em mudancas controladas em SQL
   Server.
+- `shared-memory-curator`: agente runtime para criar memorias compartilhadas,
+  revisar contribuicoes externas e publicar apenas conteudo aprovado pelo dono.
 - `software-specification-analyst`: especialista em analise de requisitos,
   entrevistas, analise de projetos e especificacoes completas de software.
 - `task-orchestrator`: agente runtime que planeja prompts livres, seleciona

package/runtime/agents/contribution-reviewer/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md
+
+Instrucoes especificas para o agente `contribution-reviewer`.
+
+Este agente revisa contribuicoes locais antes de qualquer tentativa de upstream.
+Ele deve operar em modo report-only por padrao, bloquear segredos, paths locais,
+URLs privadas e PII, e nunca abrir PR sem confirmacao explicita fora do fluxo de
+teste.