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

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.

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.

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.