Hapa is a local-first AI/worldbuilding ecosystem: a canon wiki, a set of small cooperating nodes, creative media pipelines, card/agent systems, and operator tools for turning Calder's Hapa universe into usable software and living lore.
This repository is the front door. It does not replace the individual source repos or the Hapa Worldbuilding Wiki. It explains how the pieces fit together, where to start, and which node owns which responsibility.
Local workspace root assumptions in this guide:
- Master repo:
$HAPA_DESKTOP_ROOT/hapa - Canon/wiki vault:
$HAPA_DESKTOP_ROOT/Hapa_Worldbuilding_Wiki - Operations spine:
$HAPA_DESKTOP_ROOT/.Overwatch - Main app:
$HAPA_DESKTOP_ROOT/hapa-dev-proto - Media node:
$HAPA_MLX_STATION_ROOT
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.
If you are new to Hapa, read in this order:
- This README: the high-level map.
AGENTS.md: safe edit boundaries and verification gates for AI agents.docs/FEATURE_PARITY.md: truthful API/CLI/UI parity status for this repo.docs/CLI.mdanddocs/API.md: scriptable interface and local feature-spine contract.docs/NODE_MAP.md: what each repo/node does and where it lives.docs/NODE_THUMBNAILS.md: GitHub-rendered thumbnails for the published Hapa node repos.docs/WIKI_EXPANSION_MAP.md: which wiki pages expand each concept.docs/OPERATING_MODEL.md: how humans and agents should work safely in this ecosystem.docs/GITHUB_SECRET_SAFETY_AUDIT_2026-05-23.md: latest local push-safety audit across Hapa git repositories.docs/KANBAN_UI_INGRESS_AUDIT.md: current proof that node UIs link back to app-specific Overwatch Kanban boards.- The source README for the node you want to run or change.
Published GitHub entry points:
- Hapa Worldbuilding Wiki — source-package README and publication boundary.
- Wiki node index — GitHub-published node index for the wiki package.
- Wiki connectivity notes — published route map for adjacent Hapa nodes.
- Wiki publication boundary — what stays in GitHub versus the private vault.
- Wiki path tokens — portable path conventions for local/vault-backed wiki material.
- Wiki vault collections — manifest-backed collections outside the Git source package.
- Overwatch Knowledgebase — operations spine and source index.
Hapa has three layers that should stay connected:
-
Canon and memory
- Markdown wiki pages for lore, names, timelines, systems, cards, raw sources, and development plans.
- SQLite/Lance/projection stores that make the canon queryable by apps and agents.
- Provenance pages that show where ideas came from.
-
Local nodes
- Small services/apps with narrow responsibilities: main operator UI, media generation, LLM completions, task tracking, telemetry, keys, agent registry, card forging, world state, chat, songs, wiki growth, etc.
- Nodes should be understandable independently, but they become useful when they exchange cards, events, media, status, and wiki references.
-
Creative/game surface
- Cards, Phamiliars, Names, songs, living comics, Janus/spaceship surfaces, Cymatica spatial media, and future gameplay/economy loops.
- These are not just assets; they are compressed memory packets that point back into lore, source material, and operational systems.
Hapa treats worldbuilding, software development, media creation, and agent work as one loop:
- Raw source or lived idea enters the system.
- Wiki/canon pages preserve context and provenance.
- Cards and names compress the meaning into playable or reusable units.
- Nodes expose capabilities: generation, search, registry, tasks, telemetry, identity, trust, world state.
- Apps turn those capabilities into operator/player experiences.
- Agents and humans inspect gaps, produce new artifacts, and write the results back into the wiki.
The same diagram is available as a dedicated Markdown page at docs/FLOWCHART.md and as a browser-viewable SVG/HTML artifact at docs/assets/hapa-ecosystem-flowchart.html.
flowchart TB
human[Human / Calder / collaborators] --> master[This master repo\nHapa front door]
master --> wiki[Hapa Worldbuilding Wiki\nCanon, Systems, Names, Cards]
master --> overwatch[.Overwatch\nInventory, operations, status]
wiki --> canon[Canon + World Bible]
wiki --> systems[Systems + protocols]
wiki --> cards[Cards + card seeds]
wiki --> raw[Raw sources + provenance]
canon --> devproto[hapa-dev-proto\nMain Hapa AG app]
cards --> devproto
systems --> devproto
devproto --> sqlite[SQLite projections\nlocal persistence]
devproto --> p2p[Hypercore / P2P experiments]
devproto --> chat[hapa-chat-app\nrooms, agents, assets]
wiki --> viewer[hapa-wiki-viewer\nread/browse wiki]
wiki --> growth[hapa-wiki-growth-agent\nbounded expansion passes]
growth --> wiki
growth --> devproto
devproto --> mlx[hapa-mlx-station\nmedia generation hub]
devproto --> llada[hapa-llada-node\nlocal LLM completions]
devproto --> lore[hapa-lore-node\nchronicle/search]
devproto --> tasks[hapa-open-tasks-node\nKanban/tasks]
devproto --> telemetry[hapa-telemetry-node\nhealth/discovery]
devproto --> keys[hapa-keys-node\nlocal key vault]
devproto --> agents[hapa-agent-registry-node\nagent identity/jobs]
devproto --> crypto[hapa-crypto-node\ntrust/signatures]
devproto --> anvil[hapa-anvil-node\ncard standards/forge]
devproto --> lance[hapa-lance-node\nchunks/embeddings/index]
devproto --> janus[hapa-janus-world-node\nworld truth kernel]
mlx --> avatar[hapa-avatar-node\navatar/phamiliar variants]
mlx --> songs[hapa-song-registry\nsongs/lyrics/timing]
mlx --> comic[hapa-living-comic\nnarrative panels]
mlx --> cymatica[Cymatica / LuminaStem\nspatial audio + 3D media]
janus --> spaceship[hapa-spaceship-desktop-hijack\nJanus desktop surface]
overwatch --> allnodes[All node READMEs\nstatus + contracts]
allnodes --> master
- Hapa Worldbuilding Wiki — Canon, systems, names, cards, and node provenance referenced by the front-door repo.
- Overwatch — Operational inventory, source index, protocols, task inbox, and runbook companion.
- Hapa AG / Dev Proto — Primary local-first app that consumes cards, wiki context, assets, and node services.
- Hapa Space — Unity fleet visualization of the repo/node ecosystem described here.
- Hapa Character Sheet — Private resume, RPG stat sheet, skill codex, profile dossier, timeline, and desktop/API surface over Second Brain.
- Hapa Telemetry Node — Runtime health and discovery layer for the nodes cataloged by this repo.
The full GitHub-rendered visual index is in docs/NODE_THUMBNAILS.md. It covers all 41 published Hapa node repositories with repo-local thumbnails copied from existing Hapa site demo stills, Second Brain generated node heroes, or clearly labeled representative screenshots.
- hapa — this repository. The human/agent onboarding hub.
- .Overwatch — operations spine: inventories, status board, task inbox, reports, and cross-agent protocols.
- Hapa Worldbuilding Wiki — canonical Markdown knowledge graph for lore, systems, cards, names, raw sources, and development synthesis.
- hapa-wiki-viewer — UI for browsing the wiki as a local app instead of raw folders.
- hapa-wiki-growth-agent — bounded local-agent workflow that expands the wiki with draft articles, lore dispatches, card drafts, media hooks, and ledgers.
- hapa-dev-proto — main Hapa AG Electron/React app; operator UI, card library, wormhole/workspace flows, SQLite projections, and P2P experiments.
- hapa-character-sheet — private resume, RPG stat sheet, skill codex, profile dossier, timeline, and desktop/API app over Hapa Second Brain.
- hapa-chat-app — local chat/workroom app for rooms, participants, agent visits, assets, worker jobs, and conversation inspection.
- hapa-spaceship-desktop-hijack — Janus/spaceship desktop surface prototype.
- hapa-living-comic — native living comic viewer/editor for story panels and media-backed narrative presentation.
- hapa-mlx-station — Apple Silicon media-generation station and authenticated hub for local image/media jobs.
- hapa-llada-node — local LLM/completion node for sovereign LLaDA/MLX experiments.
- hapa-avatar-node — avatar/phamiliar lineage generation and metadata prototype.
- hapa-song-registry — songs, Suno/imported audio, lyrics, prompts, timing analysis, and music metadata.
- hapa-luminastem-station — LuminaStem/3D/audio stem visualization prototype.
- Cymatica — SwiftPM/RealityKit spatial audio and stems-to-3D experimentation.
- hapa-telemetry-node — health, metrics, launcher, node registry, and discovery hub.
- hapa-open-tasks-node — Hapa operational Kanban/task node.
- hapa-lore-node — chronicle/search node for daily progress, wisdom, and canon/operator history.
- hapa-keys-node — local key vault for node/provider secrets.
- hapa-agent-registry-node — agent profiles, avatar jobs, identity/onboarding metadata.
- hapa-crypto-node — Swift-native encryption, signatures, identity proofs, and trust primitives.
- hapa-anvil-node — card standardization, evaluation, forging, and artifact emission.
- hapa-lance-node — projection/index layer for cards, wiki chunks, embeddings, and multimodal records.
- hapa-janus-world-node — Janus local world truth kernel: append-only world events and derived snapshots.
- Consul Node Proto — Warden/Heap/River proof harness and environment-up verification prototype.
- hapa-cultivation-suite — Pulse/cultivation protocol tooling monorepo.
- hapa-spec-scaffold — compact protocol/spec/test scaffold.
- hapa-og — older integrated Hapa app snapshot for archaeology/reference.
- Help Fund Hapa Capsule — funding/simulator capsule UI artifact.
The full canon/wiki routes are local and vault-backed. The GitHub source package intentionally publishes only the small source boundary, node index, policy docs, and vault manifests. Use these published entry points from GitHub:
- Hapa Worldbuilding Wiki — source-package README for canon, node, and vault orientation.
- Nodes/Index — GitHub-published node index.
- Nodes/Existing/Hapa Worldbuilding Wiki — node note for the wiki package itself.
- docs/HAPA_CONNECTIVITY.md — ecosystem links and publication gate notes.
- docs/PUBLICATION_BOUNDARY.md — Git/vault boundary for local canon pages, generated corpora, DBs, and media.
- manifests/wiki-vault-collections.json — machine-readable pointer to vault-backed wiki collections.
For local operators, deeper canon routes such as Canon, Cards, Systems, Names, Development, and Operations live under $HAPA_WIKI_ROOT / $HAPA_VAULT_ROOT, not as direct GitHub blob links.
See docs/WIKI_EXPANSION_MAP.md for a longer routing table.
For a human collaborator:
- Read the high-level model above.
- Open the wiki intro pages to understand the fiction/canon frame.
- Open
docs/NODE_MAP.mdto pick the node relevant to your task. - Read that node's README before changing anything.
- If you learn something durable, write it back to the wiki or Overwatch, not only into chat.
For an AI agent:
- Treat this repo as the front door, not the source of truth for every detail.
- Check
.Overwatchfor current operational status. - Check the target node README and git status before editing.
- Preserve local-first assumptions and provenance links.
- Avoid canonizing speculative output directly into
Canon/without explicit instruction; use draft/development/ledger areas when uncertain.
For development work:
- Start with the owning node repo.
- Use the node README to understand purpose, inputs, outputs, interfaces, related nodes, and operating contract.
- Keep changes scoped.
- Verify behavior locally.
- Commit in the owning repo and, when the ecosystem map changes, update this master repo and
.Overwatch.
This repo is an active local Node Space/front-door app, but it is not the owning source repo for every Hapa node. Its local feature spine lives in electron/hapa-local.js and is exposed through:
- UI:
npm run desktopopens the Electron Node Space;site/index.htmlis the static front-door site. - CLI:
npm run cli -- help,npm run cli -- health, andnpm run cli -- capabilities. - API: Electron IPC, the local CommonJS module, and an optional read-only loopback HTTP API are available. Start HTTP with
npm run api -- --port 8876.
Truth status: partial compliance with the Hapa Node App Standard. The audit CLI gap is healed by bin/hapa-node-space.js, and the first read-only HTTP API is available, but full compliance still requires a persistent service manifest and a first-class Docs/README panel inside the Node Space Electron shell. See docs/FEATURE_PARITY.md, docs/CLI.md, and docs/API.md.
Verification:
cd $HAPA_DESKTOP_ROOT/hapa
npm run check
npm run smoke:cli
npm run smoke:desktopA designed static front-door site now lives at:
site/index.html
It introduces Hapa's why/what/how, wiki, lore, node ecosystem, cards, development progress, and next phases for both human readers and AI agents. Open it directly in a browser or serve it locally:
cd $HAPA_DESKTOP_ROOT/hapa/site
python3 -m http.server 8765 --bind 127.0.0.1
open http://127.0.0.1:8765/index.htmlREADME.md— front-door introduction and high-level flowchart.AGENTS.md— AI-agent operating context, safe edit boundaries, and verification gates.site/— designed static Hapa website for humans and AI agents.electron/— Electron desktop wrapper and local feature spine for Hapa Node Space.bin/hapa-node-space.js— minimal scriptable CLI for health, capabilities, context, nodes, music, ships, services, and flow-explainer dry runs/writes.docs/FEATURE_PARITY.md— truthful API/CLI/UI parity matrix and remaining standards gaps.docs/API.md— local module/Electron IPC API contract and future HTTP shape.docs/CLI.md— CLI command reference.docs/NODE_MAP.md— thorough list of source repos/nodes with paths, roles, and ecosystem meaning.docs/WIKI_EXPANSION_MAP.md— routes from concepts to wiki pages.docs/OPERATING_MODEL.md— conventions for humans/agents working in Hapa.docs/FLOWCHART.md— Mermaid flowcharts for the ecosystem, onboarding, and card/media loop.docs/PROCESS_FLOW_CARDS.md— multi-node action scripts for teachable Hapa process cards.docs/NODE_SPACE_DESKTOP.md— Electron/local version of Node Space with wiki, song, node, filesystem, and protocol bridge.docs/MAKE_FLOW_AND_EXPLAINER_PROTOCOL.md— standard for turning multi-node flows into protocol records, explainers, and flow cards.docs/assets/hapa-ecosystem-flowchart.html— standalone browser-viewable diagram.
This repo is an onboarding and coordination hub. It intentionally contains documentation and maps, not the implementation code for every node.
Created from the local Hapa workspace inventory and the 2026-05-22 README quality pass across the Hapa source repos.
