replica-omnisciente/AGENTS.md

Réplica Omnisciente — Agent Guide

Centralized brain of the Portugal Futurista agent fleet + monorepo of tools.

Repository layout

Path	What it is	Language/Toolchain
.aurelio/	Central brain: sessions, MCP servers, sync, knowledge, skills	Python, JSON
realms/	21 per-project knowledge directories (each may have its own AGENTS.md)	—
dirac/	Dirac coding agent (VS Code extension + CLI)	TypeScript, esbuild
tilth/	Code intelligence MCP server (tree-sitter, AST-aware search)	Rust, Cargo
toon/	Toon format library (monorepo)	TypeScript, pnpm
shared/	Shared protobuf library (@aurelio/shared)	TypeScript, buf
extensions/	JetBrains extension, Kimi interceptor; extensions/aurelio-vscode/ is a git submodule → code.portugalfuturista.org/portugalfuturista/aurelio-vscode	TypeScript
aurelio-theia/	Theia IDE monorepo — git submodule → code.portugalfuturista.org/portugalfuturista/aurelio-theia	TypeScript, lerna
dashboards/	Media explorer dashboard	TypeScript
infra/	CDP bridge, lab gateway	TypeScript
scripts/	Operational scripts (sync, conscience upgrade, Kimi import)	Python
telminal/	Self-hosted Terminal-in-Telegram bot (sandboxed shell on the fleet gateway)	Python, Telethon

Build commands by subproject

dirac/

cd dirac
npm run install:all          # install deps (root + webview-ui)
npm run protos               # REQUIRED before build — generates protobuf TS
npm run build                # esbuild bundle
npm test                     # unit + integration
npm run lint                 # biome lint

Dirac has its own AGENTS.md with architecture details.

tilth/

cd tilth
cargo build --release        # release build
cargo test                   # unit tests
cargo clippy -- -D warnings  # lint
cargo fmt --check            # format check

Tilth has its own AGENTS.md (MCP tool usage) and CLAUDE.md (architecture).

toon/

cd toon
pnpm install
pnpm build                   # build all packages
pnpm test                    # test all packages
pnpm lint                    # eslint

shared/

cd shared
npm run gen:proto            # generate protobuf types from .proto
npm run build                # tsc compile

Three-tier config cascade

~/.aurelio/config.toml              # Global defaults
<workspace>/.aurelio/config.toml    # Workspace overrides
realms/<name>/.aurelio/             # Realm-specific memory

Resolution: Realm > Workspace > Global (most specific wins).

Provider registry (single source of truth)

All Hermes-provider surfaces are driven from one file:

.aurelio/providers/registry.yaml       # edit THIS
.aurelio/providers/dist/               # generated mirrors (do not edit)
  portal.providers.json                # -> aurelio-theia ProviderCatalog / Gabinete Hub
  mcp.providers.json                   # -> model_router.py runtime registry
  dirac.providers.json                 # -> dirac/src/shared/providers/providers.json

Covers the full Hermes parity set: openrouter, openai-codex (OAuth), nous (OAuth), zai, kimi-coding(-cn), minimax(-cn), bedrock, openai, anthropic, gemini, moonshot, qwen, qwen-code, alibaba-cloud, plus CLI-subprocess providers claude-code, antigravity, mimocode, and local. Each entry declares surfaces: [hermes, dirac, mcp, portal], protocol, auth, models, context window, streaming + fallback.

Regenerate mirrors + patch Dirac after editing the registry:

python3 scripts/generate-provider-mirrors.py --write-in-place
python3 scripts/generate-provider-mirrors.py --check      # CI guard: exit 1 if dist/ stale

The MCP model_router.py loads mcp.providers.json at import (falls back to a small builtin set if absent). The Theia backend exposes the same data at GET /models/providers via aurelio-backend/src/models/ProviderCatalog.ts, which is what populates the chat widget's provider picker and what porta.portugalfuturista.org re-serves at /api/models/providers.

Mirror pipeline (upstream → self-hosted mirrors)

One-way replication of Savearth upstream sources into self-hosted mirrors, with RL feedback. Agents work on the mirrors; originals stay authoritative.

GitHub (SavearthTech/*) ──► Forgejo  (code.portugalfuturista.org)
Jira Cloud              ──► Plane    (plane.portugalfuturista.org)
Confluence Cloud        ──► Outline  (docs.portugalfuturista.org)

File	Role
.aurelio/mirrors/sync-mirrors.yaml	Edit this — sources, targets, auth refs
.aurelio/mirrors/dist/	Generated catalog (do not edit)
scripts/sync-mirrors.py	The engine: --sync, --check, --write-in-place
.forgejo/workflows/mirror-sync.yml	CI: runs every 15 min

Registry: .aurelio/mirrors/sync-mirrors.yaml. Tokens in env vars (never in the YAML) — see .env.example for the full list. Full guide: .aurelio/mirrors/README.md.

python3 scripts/sync-mirrors.py --sync              # all targets
python3 scripts/sync-mirrors.py --sync forgejo      # one target
python3 scripts/sync-mirrors.py --write-in-place    # regen dist after YAML edit
python3 scripts/sync-mirrors.py --check             # CI guard

Sync outcomes emit RL reward signals to .aurelio/brain/trajectory-rewards/mirror-sync.jsonl — consumed by the GRPO/DPO trajectory training pipeline.

CLI guides & service lenses

Self-hosted first policy: dev work targets our own services; public clouds only when explicitly required.

Layer	Location
CLI install guides	docs/guides/cli/ (gh/tea/acli/aws/gcloud/az, kubectl/helm/tofu/ansible/docker, cloudflared/wrangler/vercel/netlify/flyctl/doctl, mosquitto/esptool/arduino-cli/platformio, yocto/buildroot/uboot/cross-toolchains) — index: docs/guides/README.md
Self-hosted guides	docs/guides/selfhosted/ (cloud-emulators: MinIO + LocalStack v3 + Azurite on lattepanda)
Agent skills	.aurelio/skills/cli-{forge,atlassian,aws,gcloud,azure,devops,edge,iot}, .aurelio/skills/embedded-linux
Connector registry	.aurelio/connectors/registry.yaml — categories saas|cad|daw|edm|devops|cloud|iot|other; regenerate mirrors with python3 scripts/generate-connector-mirrors.py --write-in-place
gbrain lens packs	aurelio-gbrain/src/core/schema-pack/base/gbrain-{creator,investor,engineer,devops,cloud,iot,everything}.yaml

Self-hosted endpoints (LAN): Forgejo https://code.portugalfuturista.org (default forge, CLI = tea), MinIO 192.168.0.40:9000 (S3, Terraform state backend), LocalStack 192.168.0.40:4566 (AWS dev), Azurite 192.168.0.40:10000-10002 (Azure storage dev), Vaultwarden (secrets/tokens).

Brain sync

Push local brain to CT 208 (Gabinete):

python3 .aurelio/sync.py --push

Pull from CT 208:

python3 .aurelio/sync.py --pull

Requires SSH to root@192.168.0.38. Uses pct push/pct pull (not direct rootfs paths — CT 208 uses LVM).

Agent → brain import (unified)

One importer fans every coding-agent's local artifacts into the brain as session-<source>-<id>/ (session.jsonl, session_memory.md, summary.md, metadata.json). Idempotent (content-addressed — re-running writes 0 files).

python3 scripts/sync-agents-to-brain.py --skip-active            # all sources
python3 scripts/sync-agents-to-brain.py --source claude-code     # one source
python3 scripts/sync-agents-to-brain.py --dry-run                # preview
python3 scripts/sync-agents-to-brain.py --summary                # JSON totals

Sources: kimi, hermes, claude-code, antigravity, qwen-code, mimocode. Adapters live in scripts/agent_importers/adapters.py; the shared normalizer + writer is scripts/agent_importers/engine.py. --skip-active drops sources modified in the last 60s.

scripts/sync-kimi-to-brain.py is now a thin wrapper that delegates to sync-agents-to-brain.py --source kimi — existing invocations keep working. Kimi plans from ~/.kimi/plans/ still sync to .aurelio/brain/kimi-plans/.

Run the import before sync.py --push to broadcast to the fleet.

Chat history sources

Source	Location	Sync
Aurélio	<workspace>/.aurelio/brain/session-*/	VS Code extension + sync.py --push
Antigravity	~/.gemini/antigravity/brain/	Fallback brain directory
Kimi	~/.kimi/sessions/<hash>/<uuid>/	scripts/sync-agents-to-brain.py --source kimi
Hermes	~/.hermes/sessions/<profile>/<id>/	scripts/sync-agents-to-brain.py --source hermes
Claude Code	~/.claude/projects/<cwd>/<uuid>.jsonl (+ subagents/agent-*.jsonl)	scripts/sync-agents-to-brain.py --source claude-code
Antigravity CLI	~/.gemini/antigravity-cli/conversations/*.db (SQLite)	scripts/sync-agents-to-brain.py --source antigravity
Qwen Code	~/.qwen/projects/, ~/.qwen-code/sessions/	scripts/sync-agents-to-brain.py --source qwen-code
MiMo Code	~/.mimocode/plans/, ~/.config/mimocode/	scripts/sync-agents-to-brain.py --source mimocode

Known Kimi stores: primary (~/.kimi/sessions/) and professional (/home/fcunha/antigravity-envs/professional/.kimi/, nested subagent layout).

Parent workspace sync

Savearth parent workspaces (aws-iot-core-poc, hardware-devicesFirmwareTest, savearth-iot-infrastructure, savearth-hw-project) should run .aurelio/sync.py --pull to receive brain updates.

CI/CD

System	Workflow	Trigger
GitHub Actions	extensions/aurelio-vscode build + deploy to CT 205	Push to main touching extensions/aurelio-vscode (submodule pointer) or .gitmodules; checkout uses submodules: true
Forgejo	aurelio-sync.yml — conscience upgrade + brain push to CT 206	Push to main

MCP servers

Defined in .aurelio/mcp_config.json. All are remote (mcp-remote to *.portugalfuturista.org), not local processes. Key ones: savearth-mcp, savearth-workspace, electrical-eda-mcp, knowledge-mcp, codebase-memory-mcp.

Infra targets

CT	Name	IP	Purpose
205	Firmware store	192.168.0.15	VSIX distribution
208	Gabinete	192.168.0.38	MCP gateway, central brain host
206	Lab gateway	192.168.0.38	Hardware lab (olhos-de-orpheu)
215	pf-matrix	192.168.0.10	Matrix Synapse (matrix.portugalfuturista.org); Hermes bot @hermes:matrix.portugalfuturista.org
217	pf-hermes	192.168.0.27	Hermes gateway 24/7 (Signal/Telegram/Matrix, E2EE); workspace ~/workspace clones from Forgejo LAN (192.168.0.9:3001)

Three Proxmox hosts in cluster portugalfuturi: asus (192.168.0.38 — CTs 202-220, incl. pf-matrix), gigabyte (192.168.0.104 — CTs 200-211 + Docker media stack + signal-cli daemon on :18088), and lattepanda (192.168.0.40 — Docker on host: cloud emulators MinIO :9000/:9001, LocalStack v3 :4566, Azurite :10000-10002, compose at /opt/cloud-emulators/, see docs/guides/selfhosted/cloud-emulators.md). Cloudflare tunnel pf-tunnel-v2 runs on asus (/etc/cloudflared/config-v2.yml).

Hermes gateway runs as a system service on CT 217 (hermes-gateway.service, user hermes); the laptop keeps hermes CLI for local chat only (laptop gateway service disabled). Platform creds live in /home/hermes/.hermes/.env (TELEGRAM_*, SIGNAL_* (LAN-direct to .104:18088), MATRIX_*). State migrates via hermes backup → hermes import.

Client onboarding (replicating into new projects)

Each Portugal Futurista client gets its own replica-omnisciente — a self-contained agent fleet brain with the same power set: .aurelio/ (config cascade, brain, skills, providers, connectors, MCP, identity/heteronyms), realms/, scripts/, and CI/CD. The onboarding tool scaffolds this from the canonical template.

Scaffold a new client

# Interactive wizard (recommended for first-time use)
python3 scripts/onboard-client.py --interactive

# CLI flags
python3 scripts/onboard-client.py \
    --client-name "Acme Corp" \
    --git-url https://github.com/acme/replica-acme \
    --lead-engineer "Jane Doe" --lead-email "jane@acme.com" \
    --realm iot-firmware --realm-name "IoT Firmware" --realm-stack "ESP32, Rust" \
    --realm cloud-backend --realm-name "Cloud Backend" --realm-stack "Rust, Axum" \
    --output ~/clients/acme-corp

# JSON config file (reproducible, version-controlled)
python3 scripts/onboard-client.py --config onboarding-acme.json

# Dry run (preview the file tree without writing)
python3 scripts/onboard-client.py --client-name "Acme Corp" --dry-run

What gets scaffolded

Component	Description
AGENTS.md + README.md + .gitignore + .env.example	Root project files with client identity
.aurelio/config.toml	Three-tier config cascade root
.aurelio/brain/ + memory/ + plans/ + sessions/	Brain storage (empty, ready to fill)
.aurelio/identity/heteronyms.json + heteronimos/*.md	Team members as heteronyms (voices)
.aurelio/providers/registry.yaml	AI provider registry (OpenRouter, Gemini, Anthropic)
.aurelio/connectors/registry.yaml	External integration catalog (git forge auto-detected)
.aurelio/skills/	Full CLI skills tree copied from canonical replica
.aurelio/sync.py	Brain sync utility (push/pull to Proxmox)
.aurelio/mcp_config.json	MCP server fleet (empty, ready to configure)
.aurelio/chronicle/	Event timeline + per-realm chronicle stubs
realms/<name>/	Per-project: AGENTS.md, .aurelio/config.toml, memory/index.md
scripts/	Onboarding CLI (self-replicating), agent importers, mirror generators
.forgejo/workflows/ + .github/workflows/	CI/CD for both forge types

Power toggles

Skip components with --no-* flags:

python3 scripts/onboard-client.py --client-name "Lite" --no-skills --no-connectors --no-ci

Managing realms after scaffolding

The scaffolded project includes its own onboard-client.py CLI:

cd <client-replica>
python3 scripts/onboard-client.py add-realm my-project --name "My Project" --repo <url>
python3 scripts/onboard-client.py list-realms
python3 scripts/onboard-client.py info

Onboarding config format (JSON)

Save as onboarding-<client>.json for reproducible scaffolds:

{
  "client_name": "Acme Corp",
  "description": "IoT infrastructure",
  "git_url": "https://github.com/acme/replica-acme",
  "lead_engineer_name": "Jane Doe",
  "lead_engineer_email": "jane@acme.com",
  "realms": [
    {"slug": "iot-fw", "name": "IoT Firmware", "stack": "ESP32, Rust"}
  ]
}

Gotchas

• extensions/aurelio-vscode/ and aurelio-theia/ are git submodules — run git submodule update --init after clone; edit them in their own repos (~/portugalfuturista/aurelio-vscode, ~/portugalfuturista/aurelio-theia) and push to Forgejo.
• dirac/src/generated/ and src/shared/proto/ are protobuf-generated — don't edit by hand.
• .env is gitignored; copy .env.example for API key setup.
• Brain sync is one-directional per call: --push uploads, --pull downloads. There's no merge — last push wins.