Overwatch — Hapa.ai Node Ecosystem Knowledgebase

Maintained by: Overwatch (Cascade)

This folder is a curated, operator-grade knowledgebase for the Hapa.ai local node ecosystem across:

• Mac Studio — “Silicon Nexus” (compute lighthouse)
• Windows PC — “Red” (operator UI + local-first knowledge workspace)

It is designed so a future agent can rehydrate context quickly and operate safely even after total context loss.

Start here

1. ./.overMind
2. ./ecosystem/TASK_INBOX.md (cross-agent handoffs)
3. ./ecosystem/STATUS_BOARD.md (what exists + what’s verified)
4. ./ecosystem/INTERACTION_MAP.md (who talks to whom)
5. ./ecosystem/PORTS_AND_AUTH.md
6. ./ecosystem/TOPOLOGY.md
7. ./ecosystem/UI_SYSTEMS_PLAYBOOK.md (Hapa × Astro UXDS × 3D × shadcn/ui)
8. ./ecosystem/UI_STARTER_KIT.md (bootstrap checklists + install references)
9. ./nodes/ (node-specific docs + runbooks)
10. ./sources/SOURCE_INDEX.md (authoritative source pointers)
11. ./ecosystem/CULTIVATION_CHECKLIST.md (how to keep docs healthy)
12. ./ecosystem/BRIEFING_PROTOCOL.md (how to write check-ins/briefings + test cards)
13. ./ecosystem/ENVIRONMENT_SPOT_CHECK_PROTOCOL.md (preflight before build/test; anti-hang)
14. ./ecosystem/HUMAN_PILOT_QUOTES_PROTOCOL.md (how to capture “Quotes from Human Pilot” → lore + mechanics)
15. ./ecosystem/TEST_CARD_DECK.md (runnable validation cards)
16. ./ecosystem/GIT_UMBRELLA_PROTOCOL.md (umbrella superproject + submodules)
17. ./ecosystem/ARTIFACT_VAULT_PROTOCOL.md (artifact vault rules; outputs live outside Git)
18. ./docs/PUBLICATION_BOUNDARY.md (Git source versus companion/vault boundary)
19. ./docs/PATH_TOKENS.md (portable $HAPA_* root tokens)
20. ./agents/ (agent profiles + skill inheritance)
21. ./ecosystem/IDENTITY_SKILLS_INHERITANCE_PROTOCOL.md + ./agents/ (agent profiles; loadable skill bundles)

Quick UI bootstrap helper (guides/audit/scaffold):

• python3 $HAPA_OVERWATCH_ROOT/ecosystem/hapa_ui_starter.py --help

Scope

• Protocols: Integrity/Flow/Form/Decoration, truth hierarchy, multi-agent claims/trails.
• Network spec: how nodes discover/connect, what the stable API surfaces are.
• Capabilities: what each node can do today (and what is planned).
• Operational runbooks: how to start/stop/validate nodes, and how to debug failures.

Non-negotiable invariants (summary)

• Integrity > Flow > Form > Decoration.
• Truth hierarchy:
  • Hypercore/P2P = network truth.
  • SQLite = local query truth.
  • UI/APIs must not lie about partial truth.
• Validation discipline: verify from primary sources (code, live endpoints, logs, official docs).
• Multi-agent discipline: claim hot files, leave reproducible trails.

Folder layout

• ./.overMind

  • This agent’s self-definition + sharpening protocol.

• ./agents/

  • Reusable agent profiles (Identity/Skills) and session notes.
  • Example: ./agents/PROFILE__EXPERT_HAPA_SWIFT_DEVELOPER.md

• ./ecosystem/

  • STATUS_BOARD.md: what exists + current validation status.
  • INTERACTION_MAP.md: control plane wiring diagram.
  • TOPOLOGY.md: ecosystem architecture + control/data planes.
  • PORTS_AND_AUTH.md: port map, tokens, auth rules.
  • UI_SYSTEMS_PLAYBOOK.md: how to choose and apply UI systems (Astro/shadcn/3D) Hapa-style.
  • UI_STARTER_KIT.md: copy/paste bootstrap checklists + install references.
  • CULTIVATION_CHECKLIST.md: recurring doc hygiene checklist.
  • BRIEFING_PROTOCOL.md: standard for significant progress completions (briefings + test cards).
  • ENVIRONMENT_SPOT_CHECK_PROTOCOL.md: preflight before build/test to avoid hangs.
  • HUMAN_PILOT_QUOTES_PROTOCOL.md: how to capture “Quotes from Human Pilot” (HPQ entries).
  • TEST_CARD_DECK.md: runnable “test cards” mapping changes → validation commands.
  • GIT_UMBRELLA_PROTOCOL.md: umbrella superproject layout + submodules.
  • ARTIFACT_VAULT_PROTOCOL.md: artifact vault rules; outputs live outside Git.

• ./nodes/

  • WINDOWS_HAPA_AG.md: Windows node (Electron) overview + local debug API.
  • MAC_HAPA_MEDIA_NODE.md: media generation node (FastAPI + SQLite + worker).
  • MAC_HAPA_MEDIA_HUB.md: hub/router for multi-node routing + admin.
  • MAC_HAPA_LLADA_NODE.md: sovereign MLX LLM node.
  • MAC_HAPA_TELEMETRY_NODE.md: central monitoring + discovery hub (UI + API + CLI).
  • MAC_HAPA_LORE_NODE.md: lore/canon recording node (.bardClass).
  • MAC_HAPA_OPEN_TASKS_NODE.md: task-truth node (UI + API + CLI).
  • MAC_HAPA_KEYS_NODE.md: local key vault (API keys; UI + API + CLI).
  • MAC_HAPA_CRYPTO_NODE.md: Swift-native cryptography service.
  • MAC_HAPA_AGENT_REGISTRY_NODE.md: agent onboarding/registry + avatar job tracking.
  • MAC_HAPA_CULTIVATION_SUITE.md: Pulse Node Proto Dev / Hapa Cultivation Suite (capsules + protocol tooling + parity API + Pulse worker scaffold).
  • MAC_CONSUL_NODE_PROTO.md: local node scaffold (API + UI + CLI parity).
  • MAC_HAPA_LUMINASTEM_STATION.md: LuminaStem 3D prototype artifact.
  • MAC_HAPA_AVATAR_NODE.md: Hapa Avatar Node (prototype/spec).
  • MAC_CYMATICA_VISION.md: Cymatica Vision (SwiftPM) runbook.

• ./sources/

  • SOURCE_INDEX.md: authoritative file pointers across repos.

• ./pilot_quotes/

  • One-file-per-quote HPQ entries (Human Pilot direction → lore/mechanics → later Montessori cards).

• ./agents/

  • Agent profiles (expert “loads”) and overlays (see ./ecosystem/IDENTITY_SKILLS_INHERITANCE_PROTOCOL.md).

Update discipline

• Prefer additive updates over rewriting history.
• Always include:
  • what changed
  • how to validate
  • source pointers
• Keep API contracts versioned (and documented with api_version).

Repository role in Hapa

Verified from this repository: Overwatch is a documentation-first operations knowledgebase for the local Hapa.ai node ecosystem. It keeps source-linked projections for workspace inventory, node status, ports/auth, interaction topology, task handoffs, check-ins, agent profiles, UI standards, and validation protocols.

Inferred operational role: this repo behaves as a watchtower/control-plane memory layer rather than a runtime service. It does not expose a primary application port itself; instead it documents the ports, tokens, and validation paths of sibling Hapa nodes.

Global wiki anchors:

• $HAPA_WIKI_ROOT/Nodes/Existing/Overwatch-Knowledgebase.md
• $HAPA_WIKI_ROOT/Operations/Overwatch Knowledgebase.md

Run and verification commands

This repository has no root package.json, pyproject.toml, or Package.swift as of the 2026-05-21 documentation/licensing pass, so there is no single build command. Cheap validation commands are:

• python3 ecosystem/hapa_env_spot_check.py --project $HAPA_OVERWATCH_ROOT --timeout-seconds 5 --json
• python3 -m py_compile ecosystem/hapa_env_spot_check.py ecosystem/hapa_ui_starter.py
• git status --short --branch

Node-specific runbooks under ./nodes/ and repo/source pointers under ./sources/SOURCE_INDEX.md remain the source of truth for sibling runtime commands.

Data inputs and outputs

Primary inputs are local repository docs, source pointers to sibling Hapa repos, node capability/API notes, status/check-in files, and operator/agent handoffs. Primary outputs are Markdown runbooks, ecosystem maps, node profiles, protocol files, check-ins, test cards, and wiki projections.

License and attribution

Project-level license: MIT under Hapa.ai / Calder Wong. See ./LICENSE.

Contributor attribution option: contributors may opt into Bananas work-contribution tracking for attribution. Bananas participation is optional and additive; it does not change the MIT project license and should not remove or overwrite any third-party license notices preserved in this repository or referenced artifacts.

Security note

• Treat bearer tokens like passwords.
• Default to loopback bind for dev.
• Only bind to LAN (0.0.0.0) intentionally, and prefer LAN/VPN/SSH tunnel over public exposure.

Hapa ecosystem context

Shared ecosystem pattern

Hapa is built as a constellation of modular nodes. Each node owns a focused capability, but participates in a shared protocol for provenance, handoff, cards, memory, and operations.

Every node is designed for both human operators and AI agents. The target contract is three surfaces: a UI for direct human review/control, an API for node-to-node and agent calls, and a CLI for scripted runs, audits, and handoffs. Individual repos may be at different maturity levels, but the public contract is that humans and agents can inspect, operate, and verify the node.

Hapa nodes power AI agents and avatar-agents that build new nodes and enhance existing ones. As work moves through the ecosystem, it is mined for utility, wisdom, and repeatable logic, then distilled into Hapa Cards: portable packets of skills, context, memories, and operational patterns.

Humans and AIs use Hapa Cards to discuss, ideate, prototype, and deploy increasingly complex workflows through a playable, card-collecting mechanic. Collaboration history, skills, work artifacts, and canonical decisions are stored in hapa-second-brain, enriched into Hapa Worldbuilding Wiki entries, and converted back into cards. Avatar-agents can also be combined or specialized into purpose-built identities with their own storage, lore, canon, card decks, skills, and protocols.

Purpose

Curated operations knowledgebase for the Hapa multi-repo ecosystem: inventory, source index, task inbox, protocols, node runbooks, and cross-agent handoffs.

Current status

• Status: active operations spine.
• Local source root: $HAPA_OVERWATCH_ROOT.
• This README is intended to be useful to both human operators and future agents: it should explain what the node is for, what it consumes, what it emits, how it connects to other Hapa nodes, and what should stay out of git.

Inputs

• Human pilot instructions and agent check-ins
• Repo audits, node runbooks, source inventories, and status boards
• Validation reports from individual Hapa nodes

Outputs

• Workspace inventory, source index, task inbox, protocols, and runbooks
• Durable goal/report/audit artifacts for future agents
• Cross-node operating context for Hapa development

Interfaces

• Markdown knowledgebase under ecosystem/, nodes/, sources/, protocols/
• Git history for operational changes
• Task inbox for cross-agent handoff

Related Hapa nodes

• Hapa AG / Dev Proto — Primary local-first app; many nodes feed it cards, assets, chat, debug, or projection data.
• Hapa Worldbuilding Wiki — Canonical Markdown graph for lore, nodes, names, cards, systems, and provenance.
• Hapa Telemetry Node — Discovery/monitoring hub for node health, capabilities, launchers, and relationships.
• Hapa Keys Node — Local key vault used by authenticated nodes and tools.
• Hapa Lore Node — Chronicle/canon service for daily progress, lore, and searchable wisdom.
• Hapa Anvil Node — Card standardization/evaluation/forge node for turning raw card ideas into usable artifacts.
• Hapa Janus World Node — World-state truth kernel and event tape for Janus/desktop simulation work.
• Hapa MLX Station — Apple Silicon media-generation station that produces visual/audio assets for cards, wiki, and production runs.
• Hapa Lance Node — Local indexing/projection layer for cards, wiki chunks, embeddings, and multimodal records.

Operating contract

• Treat generated media, local databases, model weights, dependency folders, build outputs, app bundles, and secrets as runtime artifacts unless this README explicitly says otherwise.
• Prefer loopback/local operation first; expose network services only with explicit auth and operator intent.
• When this node produces artifacts for another node, record enough provenance for the receiving node or wiki page to recover the source path, command, prompt, or API request.
• Keep README.md, LICENSE, NOTICE.md where applicable, and repo-local screenshots current as the node evolves.

See It In Action

Open the Hapa Node Atlas demo