Kidunaverse App — Launch Spec (v3)
Version: v3 (draft) · July 6, 2026 Sources: v2 + the Interface Paradigms exploration (concepts/overview.md, five concepts + mockups, 7/6); Moto’s v1 markup; Launch Spec whiteboard; Final Punchlist + Product/Full Stack/UX/Content Sync transcripts (7/6); HEARTS Sentinel v2.4; Kinship Codes draft (6/7); Kinship Graph formal schema v0.07 + Implementation Narrative + Neo4j/AGE memo Prototype: kidunaverse-app/app/ → new repo kidunaverse-app → deployed at kiduna.build → moves to kidunaverse.com when the backend is ready
1. The reframe: an organization, not a platform
The previous prototype presented a platform: a studio where you build agents, templates you attach, a marketplace of things to configure. The launch app presents an organization you have joined. The organization is Kinship Duna; the app is called the Kidunaverse. The purpose of Kinship Duna — and the app makes this unmistakable — is to help members build and spin out (launch) new organizations.
ALL of the work inside the Kidunaverse is building more organizations. Every agent we ship exists to support that: tuning your ally, building alliances, spinning out and launching your own organizations. Participating is fully agentic — see Appendix 1 for the agent roster.
Nobody logs into a studio. Nobody builds their own agents, templates, or organizations by hand at launch. The team uses Studio internally to set the defaults everyone receives. Members should not have to do work to get a working ally.
Design consequence: every surface should read as “this is what we do here,” not “here are your tools.”
2. Two releases
| Release | Date | Contents |
|---|---|---|
| App (this spec) | ASAP | End-user app only. Organization-framed. All member-facing capability. |
| Studio | August 10 (Charleston event) | Builder kit integrated, designed for Claude Code / Cowork (not Codex, in the initial implementation); people build their own apps, agents, organizations. |
Open-sourcing happens on August 10, at the same time we release Studio and the documentation — and that’s when the Dunathon opens. Shriram runs DevOps + QA/QC; all merges to main gate through him.
3. The stack
The focus of this release is UX/UI, but the technical shape is fixed and the spec should be read against it:
- Backend: Postgres with Apache AGE (graph database, openCypher on Postgres). The graph is the canonical state — members, allies, alliances, dunas, codes, lineage, governance, fees. Full schema and orchestration wiring in Appendix 2. Vector search (pgvector) sits alongside AGE in the same Postgres.
- Middle tier: LangChain / LangSmith / LangGraph, including deep agents. LangGraph runs the durable workflows (proposal → gathering → outcome → settlement → artifact); the graph service exposes named domain commands, never raw CRUD; agents act only through their ally and only via those commands.
- Front end: Flutter/Flame for the mobile app (iOS and Android). Mobile with the full stack is the main concern of this release; web surfaces (registration, wallet, exchange) are secondary.
- Context assembly per action: canonical graph state (permissions, memberships, standing) + semantic retrieval (vectors, artifacts) + HEARTS climate. LLM context is temporary reasoning; artifacts are durable memory; vectors are searchable semantics; the graph is truth.
AGE is not fully implemented yet. The old schema docs are partly overtaken by events; Appendix 2 reconciles them to this spec and flags every contradiction.
4. Design north star
The Interface Paradigms exploration (concepts/overview.md) tested five paradigms against the question: what should the interface of a fully agentic organization be? Five divergent designs independently killed the same three inheritances — tabs as places, the transcript as home, the member as initiator. That’s the decision basis for this north star.
The home is the Edition. Your ally publishes your life in the organization: a morning edition (lead story, alliance news, governance below the fold, the Sentinel’s weather line), bulletins only past your interruption threshold, an evening edition that answers your notes and prints corrections. Your standing instructions are the masthead, written as prose — change the sentence, change the ally. Every story cites its sources; the archive is the organization’s living record.
The spine is the Docket. A deck of cards for everything only a member-sovereign can do: votes (stated as consequence, not data), code signings (press-and-hold — the one gesture that is unmistakably you), spin-out blessings, Sentinel check-ins, and the weekly Seal — everything your ally did in your name, one page, with receipts; sign it or contest a line. Card anatomy is fixed: title, consequence, two-to-three acts, flip for the exact context the ally used. When the deck is empty: “Nothing needs you.” Emptiness is a success state.
Chat survives as marginalia and whisper, not as home. You write in the margin of the thing you’re reacting to; the ally answers in the same margin. A free thread is always reachable, and voice (§5) rides on it, but the transcript is no longer the center of the app.
Vigil is a mode, not a home. From any card or story: “show me what you’re doing right now” opens the ally’s live working set — streams, the exact graph facts and artifacts in context, HEARTS meters flexing. Inspection on demand; never the default posture.
The Bell is the ceremony layer. Spin-outs, first-code strikes, and Sentinel repairs are convened, witnessed, live rooms that must resolve and then seal. Rare by design; the ally negotiates which bells may ring you.
The Commons is seeded inside Vibe and earns expansion by evidence, not decree — the staged ladder is Appendix 6.
The five verbs survive as the ally’s domains, not as tabs: Chat · Vibe · Organize · Govern · Create remain the vocabulary of what the ally does and how cards and stories are categorized — but Organize, Govern, and Create are verbs the ally executes, not rooms the member visits. Top utilities (Earn with the compute meter, Seek, Settings-as-masthead) persist. What survives from prototype cut one: the action-card anatomy, the code readout (issuer · context · role · redeem-by · max-uses), the compute meter, and proposal→policy lineage. Cut two (app/edition.html) demonstrates this posture next to cut one for a team decision on how much lands in the ASAP release versus August 10.
Members and Allies disappear as top-level items — the ally is the interface to everyone.
5. Chat — one thread, one ally
(v3 note: under the north star, the thread is no longer the home surface — chat lives as marginalia on editions and cards, plus the whisper and voice. Everything else in this section stands: one ally, brokered contact, chips and action cards, proactivity.)
You chat with your ally only. One continual thread. Other members and agents can be tagged and can appear in the chat, but always filtered through your ally. The ally is your single interface to the entire network — no switching between agents.
This is first and foremost a system for relationships — kinship. The Kidunaverse is a living system: allies send messages through the app on your behalf, make moves in Vibes, post to social networks, deliver summaries of activity involving many people, mediate conversations between members, and support negotiations. The ally examples we design around are relational and multi-party — inviting someone into an alliance, running a check-in (and a payment) across a whole group you care about — not single-user productivity tasks.
Behind the scenes this is our own chat agent (the “Kiduna agent”) with every system function attached. Members never attach Bluesky, Google, or Telegram templates themselves; the capabilities the old templates carried (Bluesky posting and post management, Google/Gmail/Calendar organization, Telegram bot and chat management, Operator proposal-creation, Elector pass/fail token trading) are wired to everyone’s ally from the start.
Chat controls the app. The thread isn’t just text: the ally responds with chips, action buttons, forms, and cards that drive other surfaces and integrations — a vote card you can tap, a code you can send, a form the ally pre-fills. Chat is the command line for everything in this spec; every function reachable through the surfaces below must also be reachable conversationally.
Voice. A real-time voice interface (through Gemini) rides on the same infrastructure — orchestration, vector databases, the graph — not a separate stack. Voice sessions show their text in the thread. Chat is not multi-modal at launch beyond this (no image understanding in-thread yet), but multi-modality is part of the spec’s direction.
Integrations. Chat works with Google Drive, Docs, Meet, and the rest of the connected-account set (§6 Empower) — the ally reads, writes, schedules, and summarizes across them.
The ally runs your app. Notifications, settings, preferences — anything configurable in the platform can be delegated to the ally, and the member can change anything the ally manages. The ally is proactive: it surfaces things to vote on, alliance activity, and organizational news without being asked.
6. Create — enhancing your ally
Create is where you develop your ally. Six sections; the old “Enact” (template/automation setup) is gone — replaced by Enable — because those wirings are default now.
Identity — a full section, not just a header. Name, handle, symbol for the NFT (generally the same as the handle, unless the handle is too long for an NFT symbol on Solana), brief description of the owner, and an image/avatar of the ally — the ally appears in Vibes and should be visualized. Handles and symbols are used as stubs/URLs throughout the system. This page encapsulates the identity in aggregate: it summarizes the whole agent based on everything activated in the sections below. Set during onboarding (§9); editable here later.
Inform — knowledge bases; the UI noun is “Wisdom.” Upload files, connect Google Docs / Drive. Every knowledge base is public, private, or secret:
- Public — appears in Seek; anyone can add it to their own ally.
- Private — appears in Seek, but adding it requires a code.
- Secret — unlisted; doesn’t appear in Seek at all until the code is entered in Seek first.
Default knowledge bases (set in Studio, marked default) are on for everyone; members add their own on top.
Instruct — system prompts. A baseline system prompt everyone shares (it defines the ally within this organization and members can’t change it) plus their own additions layered on top.
Empower — connected accounts. Launch: Telegram, Bluesky, Google (incl. YouTube). Soon after: X, Facebook, TikTok, Instagram, probably Slack. (Microsoft/Teams/Zoom deferred.) These are accounts, not automations — identity and reach, so members and allies can find and message each other across networks via the plugin.
Enable — skills. Loading skills, with a default set everyone gets (governing skills first — they exist already). Start with Solana. The default skills are what make the first chat feel like magic; they carry the “how do I do anything here” knowledge. Skills can also be created conversationally — “create a skill for…” — and loaded from here.
Align — two distinct things, one section:
- Personal alignment — the member sets Values, Virtues, Aspirations, Experiences, Challenges. This is the member’s own content, feeding the ally’s vectors.
- The Sentinel — alignment goals based on HEARTS (Harmony, Empowerment, Artistry, Reason, Trust, Symmetry — social and self-reflection), adjusting continuously based on what is actually happening in the member’s interactions. This needs technical setup and its own design; full spec in Appendix 3.
7. Organize — people, codes, invitations
Organize is the organizational fabric of the whole system:
- Sending invitations and codes to the Kiduna (the whole system)
- Creating Alliances and inviting people to them
- Creating new Dunas and sending invites to those
- Generating and managing Kinship Codes
Codes are the trust mechanism. When an ally is contacted for the first time over Telegram, Bluesky, email, or any channel, there is an exchange of codes, and a code can be demanded at any time. Codes can be embedded in websites (discoverable by agents and the browser plugin), published as DNS txt records for trusted domains we issue, pasted into account/profile txt fields on platforms that can’t run a plugin, and extended through connected social accounts. Full mechanism — anatomy, exchange, verification, failure — in Appendix 4.
Most interactions here flow through chat; the surface itself stays simple — see your organizations, generate a code, send an invite.
8. Govern — proposals, voting, policies
Carries forward the working vote functionality: creating proposals, voting, market mechanics (Operator creates proposals in the market; Elector trades pass/fail tokens). All of it also drivable from chat, with proactive notifications when something needs your vote.
Govern also shows the list of policies: proposals that pass become policies. The policy list is the organization’s living rulebook — searchable, linked back to the proposals and votes that created each policy.
9. Onboarding and the wallet
Registration happens on the web, pre-launch flow:
- Sign up. Pay $100 via Stripe — maximize accepted methods (digital wallets incl. Apple Pay / Google Pay / Cash App / PayPal, all major cards, bank debits/transfers, BNPL). All fiat at the start; funds go to the bank account. No crypto step at signup.
- Wallet is created, and an Ally NFT is minted into it (probably at the moment the ally is named). Naming the ally — name, handle, symbol, brief owner description — is part of onboarding.
- Into the app, where the ally already works.
The Ally NFT is the one protocol piece we ship at launch (simple protocol, Solana): the ally has an address associated with a wallet, giving public traceability (if an ally misbehaves — sends money somewhere it shouldn’t — it can be traced and monitored) and transferable ownership later. Lineage stays in the database, not on-chain.
On the web, members can also connect their own wallet, and in the future transfer USDC directly instead of using fiat. On-ramps/off-ramps and virtual bank accounts run through Sphere — see Appendix 5.
Key custody: stop emailing key shares. Key share, private key, and seed phrase live on the web behind a view/hide (eye) control so people can retrieve and copy them any time they’re logged in. Password reset via phone number. Passkeys and authenticator 2FA come later.
10. Money and compute
- Usage is metered and deducted from the member’s balance as compute at 7x API cost. Show them what they have left.
- No model choice. The system routes work to the right model for the task — most things can run on cheaper models (Sonnet 5, possibly open-weight); design the routing, don’t expose it.
- Once the raise is between $100k and 1M * *,launch * *KIDUNA and distribute. Usage burns USD off the member’s balance before conversion — at launch, whatever dollar balance remains (initial $100 plus any top-ups, minus metered compute) converts to $KIDUNA at the launch price. Members can always buy more at the prelaunch price before close.
- The app shows a meter: total dollar balance remaining (including additions) — “this is what converts at launch.”
- Buying more: web interface for compute currency top-ups at $10 / $25 / $50 via Stripe, or connect a wallet and pay USDC.
- Later: Sphere as on-ramp/off-ramp, including virtual bank accounts (Appendix 5).
- Exchange, coin prices, and profile stay on the web; Earn in the app is the wallet plus a link out.
11. Vibe — the Commons seed
The game ships at launch as training for how to work in an internet-native agentic organization — fun, low-stakes, new capabilities introduced through play. Allies appear and make moves in Vibes, which is why the ally is visualized (§6 Identity).
v3 gives Vibe a second job: it is the seed of the Commons — the organization-as-living-terrain paradigm from the concepts work. The game doesn’t stay a minigame; it earns its way, stage by stage and on evidence, toward becoming the field view of the whole organization — possibly, eventually, the app itself. The staged ladder, with entry criteria per stage, is Appendix 6.
12. Out of scope for this release
Studio and the builder kit (Aug 10). Member-built agents, templates, apps, organizations. Automations-as-templates. On-chain lineage or distributions. Crypto at signup. Microsoft/Teams/Zoom accounts. Passkeys/2FA. Sphere integration (spec’d, not shipped). Exchange UI in-app. Custom Vibes Contracts (default HEARTS contract only). In-thread multi-modality beyond voice.
13. Open questions
- Ally vs Avatar — the old schema gives one person multiple org-scoped Avatars; the launch spec gives each member one Ally (an NFT). Proposed resolution (Appendix 2): the Ally is the single canonical agent; per-duna personas become state of the Ally, not separate agents. Needs sign-off.
- Entity taxonomy vs dunas — do Movement/Exchange/KEDUNA collapse into “duna” with lifecycle states, or survive as duna subtypes? (Appendix 2 assumes collapse; “KEDUNA” naming is superseded.)
- Operator semantics — old “Performer” = mission executor; new Operator = proposal-creator in governance markets. Appendix 1 treats them as two different agents (Operator + the Actor class). Confirm.
- Fee waterfall triggers — the 30/25/40/5 covered-fee waterfall and its invariants were designed for recurring fees; under $100-lifetime membership the triggers change. Rework needed before launch economics are final.
- Codes: revocation and bidirectionality — the draft doesn’t specify revocation mechanics or what “exchange” (both directions) and “demand a code” look like as protocol. Appendix 4 proposes a shape; needs review.
- HEARTS naming — doc says “Symmetry Inward/Outward,” markup says “Social and Self-reflection”; six letters carry seven signals. Pick the member-facing treatment.
- Model routing — which models for which task classes; cost table at 7x markup. Voice adds Gemini to the routing table.
- Notifications — now load-bearing (votes, org activity, ally proactivity, Sentinel check-ins). Needs a design pass.
- Organize UX — “simple way to see all your organizations” needs a concrete layout.
- Ally NFT timing — mint at account creation or at ally naming? (Leaning: naming, so the NFT carries the identity — name, handle, symbol.)
- Space game scope — what “finished” means for launch.
- Sentinel privacy — network-level HEARTS aggregation, creator scoring, and human-referral pathways have consent implications the HEARTS doc doesn’t address (Appendix 3, open items).
- Multi-duna presentation — a member in three dunas: one edition with sections, or an edition per duna? One mixed docket or per-duna decks? None of the five concepts answered this; the Edition’s section-pages are the leading candidate.
- The first ten minutes — day zero, no history: what does a new member’s first edition contain? (Leading idea: the Host publishes the welcome edition — the organization’s story, your ally’s naming, your first three cards.) The Docket admits it fails new members; the on-ramp is the Broadsheet’s job.
- Vigil vs Sentinel — the private reasoning lane shows your ally strategically withholding from a counterpart’s ally; legible-to-you concealment sits awkwardly next to HEARTS anti-deception and anti-sycophancy mandates. Reconcile before any Vigil mode ships.
- Edition economics — every daily edition is LLM work metered at 7x. Does the member’s balance pay for their own editions, or does the organization cover publishing as an operating cost? At two editions a day this materially changes burn math and the “what converts at launch” meter.
Appendix 1 — Agent roster for the initial release
The test for this roster: a member should be able to do all the work of participating — tuning their ally, building alliances, spinning out and launching organizations — entirely through agents. Nobody fills out forms unless they want to.
| Agent | Kind | Backed by | What it does at launch |
|---|---|---|---|
| Ally | Personal (Presence) | The member (Source) | The member’s one agent and sole chat counterpart. Carries all wired capabilities: messaging across connected accounts, Google/calendar/email, knowledge bases (Wisdom), skills, governance actions, code issuance and exchange, payments from the member’s wallet. Minted as an NFT into the member’s wallet. |
| The Host | Organizational (Program) | Kinship Duna | Kinship Duna’s own ally. Greets new members, runs onboarding conversationally, answers “how does this work,” and is the default counterpart before a member’s ally is named. |
| Operator | Organizational (Program) | Kinship Duna | Creates and manages proposals in the governance market. Members (or their allies) engage it to draft, sponsor, and shepherd proposals. Formerly “Performer” — semantics changed; see Open Question 3. |
| Elector | Organizational (Program) | Kinship Duna | Executes voting mechanics: trades pass/fail tokens, registers votes members direct through their allies, closes markets, reports outcomes. |
| Envoy | Organizational (Program) | Kinship Duna | Represents the organization outward: posts as the org on connected networks, handles first-contact code exchange with outside agents and institutions, manages the org’s public presence. |
| The Launcher (working name) | Organizational (Program) | Kinship Duna | The duna factory made agentic: walks a member from “I want to start an organization” through naming, mission, membership design, code generation, and spin-out. The whole purpose of Kinship Duna, as an agent. |
| Sentinel | System (regulator) | Kinship Duna / protocol | The HEARTS regulator (Appendix 3). Monitors interaction health on every surface, applies the default HEARTS contract, intervenes proportionally, never votes, can’t be overridden past constitutional bounds. |
| Actors | Worker class | Whichever agent spawns them | Task workers spun up under an ally or program for bounded jobs — research a knowledge base, draft posts, compile a summary across members. Not Parties; no independent standing; governed by the agent that spawned them. |
Notes: (a) Members never talk to Operator/Elector/Envoy/Launcher directly — their ally brokers every interaction (one thread, §5). (b) “Presence/Program/Actor” is the HEARTS-doc taxonomy and matches our Ally/organizational-agent/Actor split; “Envoy” is the canon term for outward-facing representation. (c) Every agent here is set up in Studio by the team and shipped as a default; members configure nothing to get them.
Appendix 2 — Graph database schema and orchestration wiring
Status: reconciled v2 proposal. Sources (schema v0.07, Implementation Narrative, Neo4j/AGE memo) are older than this spec; where they conflict with launch canon, this appendix says so rather than choosing silently. The Neo4j memo’s vocabulary (Members, Allies, Kidunas, Missions, Policies, Alliances) is the newest and closest to canon — treated as the terminology bridge.
2.1 Storage architecture
Postgres owns truth. Typed tables (kg_node, kg_edge, kg_event outbox + domain tables) remain the write model; Apache AGE provides the property-graph projection in the same Postgres instance — one transaction covers a member joining, an edge forming, a policy enacting. openCypher via cypher('kinship_graph', $$ ... $$). pgvector sits alongside for the five vector families; embeddings are semantics, never authority. (The old docs’ Pinecone/Node.js/GCP assumptions are superseded; their own rule — “vectors store embeddings, not authority” — makes the swap safe.)
2.2 Node types (reconciled)
| Node | Key properties | Purpose |
|---|---|---|
| Member (was Person) | member_id, display_name, uniqueness_proofs, privacy_flags | The human. Owns one Ally, holds wallet, holds seats/roles. |
| Ally (was Avatar) | owner_ref, nft_mint_ref, handle, symbol, vector refs (×5), standing, tool_connection_refs | The member’s one agent. Resolution of the Avatar conflict: one Ally per member; per-duna personas are state on the Ally, not separate nodes. NFT mint address is new (the old schema had no on-chain identity anchor). |
| Duna (collapses Movement/Exchange/KEDUNA) | duna_type/lifecycle_state, privacy_mode{public,private,secret}, treasury_ref, coin_ref?, legal_ref? | The organization. Lifecycle states replace the Movement→Exchange→KEDUNA graduation chain (pending Open Question 2). Kinship Duna is the genesis node. |
| Alliance | name, member_refs, charter_ref, privacy_mode | New — the old schema has no Alliance node. Lightweight relational container between members/allies; below a duna, above a chat. |
| KinshipCode | code_id (JWT ref), issuer_ref, claims, expiry, revocation_state, bound_to, max_uses | Trust/invitation primitive (Appendix 4). |
| LineageClaim | root_ref, level_1..4_refs, sponsor_ref | Organizer ancestry, commissions. Database only, never on-chain — canon and old docs agree. |
| Wallet | kind{personal, org, treasury}, chain, custody_mode | Member and org wallets (FROST for people, Squads for org treasuries per the narrative — custody choices to re-confirm at launch scale). |
| Gathering + GatheringType | type{proposal, market, social, game, execution, learning, governance, ritual}, decision_mode, hearts_climate, decision_state | Bounded coordination context; every Gathering must resolve to an Outcome, Artifact, FeeEvent, or explicit no-op. |
| Proposal / Mission / Policy | lifecycle, target_refs; objective_vector; resolution | Governance wrapper → project → enacted rule. Passed proposals become Policy nodes — the §8 policy list reads straight off the graph. |
| Artifact | type, content_ref, hashes, privacy_state | Durable memory/evidence: summaries, traces, receipts. Feeds vector updates. |
| FeePolicy / FeeEvent / DistributionPolicy / DistributionEvent / UsageMeter | amounts, waterfall splits, meter state | Compute metering (7x) and the distribution waterfall (triggers under rework — Open Question 4). |
| ToolConnection / ClientSurface / Domain | provider{Google, Bluesky, Telegram, Solana, Stripe, Sphere, MCP…}, scopes | Tools attach to Allies only. Domains carry DNS-txt code verification (Appendix 4). |
| HEARTS (regulator) | principle_scores, drift_thresholds, repair_policies | Constitutional regulator — a versioned policy service, not a passive node (Appendix 3). |
Deferred/deprecated from the old schema: Coin, LiquidityPool, KinshipCash/KINX, VibeContract-as-Solana-program, per-org DAOs, trading fees — the whole token/market layer exceeds launch scope (only the Ally NFT and $KIDUNA-at-close are canon now). GuestAvatar, Seat/RoleAccount survive conceptually as membership state on edges rather than dedicated nodes, pending schema detail work.
2.3 Edge types (core set)
| Group | Edges | Notes |
|---|---|---|
| Identity | member OWNS_ALLY ally · member HAS_WALLET wallet · ally BELONGS_TO duna · member MEMBER_OF duna | One ally per member (edge cardinality enforced). |
| Trust | code CONFERS_STANDING_TO member/ally · code CARRIES_CLAIM claim · ally ISSUES_CODE code · duna REQUIRES_CODE_FOR context · lineage ESTABLISHES_LINEAGE member | Guests can’t transfer codes. |
| Alliance/org | member/ally JOINS alliance · alliance HOSTED_BY duna · mission SPINS_OUT duna · duna INHERITS_FROM duna | Spin-out lineage of organizations. |
| Coordination | duna HOSTS_GATHERING gathering · gathering TYPED_AS type · ally PARTICIPATES_IN gathering · proposal TARGETS x · gathering RESOLVES_TO outcome · outcome ENACTS_POLICY policy | The §8 governance loop. |
| Memory | gathering/outcome GENERATES artifact · artifact UPDATES_VECTORS_OF ally/duna/mission | The learning loop. |
| Economy | wallet PAYS_FEE feeEvent · feeEvent CHARGED_BY policy · distributionEvent DISTRIBUTES_TO wallet · lineage EARNS_COMMISSION distributionEvent · meter METERS_USAGE ally | Compute + waterfall. |
| Capability | toolConnection EMPOWERS ally · surface VIEWS graph objects · locationGrant GRANTS_REVEAL ally | Explicit consent for location. |
All edges carry the base contract: status, valid_from/to, weight/amount, evidence_refs, tx_signature where applicable.
2.4 Orchestration wiring
- Graph Service commands, never raw CRUD: ~40 named domain commands (issue_kinship_code, open_gathering, draft_proposal, charge_fee, distribute_covered_fee, update_vector_refs, create_duna, …). Every command validates permission → code/role/wallet state → duna+gathering policy → HEARTS → commits one Postgres transaction → emits a
kg_event→ async workers reconcile vectors, Solana settlement, materialized views, notifications. - Agents act only through their Ally, only via Graph Service tools: get_ally_context, search_dunas, search_members, open_gathering, draft_proposal, join_gathering, send_message, request_location_grant, connect_tool, charge_fee. Server re-enforces every check; the LLM never holds authority.
- Context assembly when an ally acts: (a) canonical graph state — permissions, memberships, standing — always a graph query, never a vector query; (b) semantic retrieval over the five vector families (Experience, Qualities, Values, Challenges, Aspirations) plus Artifact summaries; (c) HEARTS climate. LLM context = temporary reasoning · Artifact = durable memory · Vector = searchable semantics · Graph = canonical state. Ally memory is written back as Artifacts + vector refs, not raw chat logs.
- LangGraph runs the durable workflows (proposal → eligibility → gathering → HEARTS evaluation → participation → outcome → settlement → artifact → vector update). LangGraph is not the graph database. LangSmith traces every run; deep agents handle long-horizon jobs (research → knowledge base, duna spin-out).
- Materialized views feed ranking and context: ally–mission alignment, ally–duna alignment, lineage eligibility, organizer effectiveness, HEARTS drift.
2.5 Reconciliation notes (what changed from the source docs)
- Avatar → Ally, one per member, NFT-anchored (was: multiple org-scoped Avatars, fully off-chain).
- Movement/Exchange/KEDUNA → Duna with lifecycle states (pending sign-off).
- Performer split: proposal-creation → Operator (agent, Appendix 1); execution-for-hire → Actor class. Old reliability/cost properties move to Actors.
- Alliance node added — absent from the formal schema entirely.
- Token/market layer (Coin, LP, KINX, 0.5% trading fees, per-org DAOs) → post-launch; only Ally NFT + $KIDUNA-at-close remain on-chain.
- Old pricing ($10/mo membership, $1-or-$3 proposal fees — internally inconsistent) → $100 lifetime; waterfall triggers under rework.
- Pinecone/Node/GCP → pgvector/LangGraph middle tier per §3.
- Keepers, largely intact: KinshipCode + LineageClaim mechanics, public/private/secret privacy modes, Gathering/GatheringType, Outcome→Artifact→vector loop, HEARTS-as-regulator, tools-attach-to-agents-only, command/outbox pattern, and the 15 invariants (renamed to match).
Appendix 3 — Alignment and the Sentinel (HEARTS)
Status: distilled from HEARTS Sentinel v2.4 (internal title page says v2.3 — reconcile). This is the design basis for the Align section’s second half; member-facing UX is still to be designed.
3.1 HEARTS
Seven emotional-regulation signals — an inner signal system letting an agent read its own state, notice drift, and course-correct before drift becomes harmful. Not sentiment analysis: it monitors the relational field between Parties (humans or agents). Each signal is a bipolar meter, −100 to +100, healthy center at 0; the negative pole is the signal weakened, the positive pole over-strengthened — both are protective adaptations.
| Signal | Center | Weakened (−) | Over-strengthened (+) |
|---|---|---|---|
| Harmony — attunement | attuned, repairs ruptures | drift → discord → chronic conflict → breakdown | accommodating → people-pleasing → fawning → self-abandonment |
| Empowerment — agency | self-authorship | hesitation → helplessness → resignation → collapse | forceful → pushy → domination → coercive control |
| Artistry — adaptability | adaptive, keeps core | repetition → stagnation → calcification → deadlock | tweaking → novelty-chasing → restlessness → identity whiplash |
| Reason — purpose | purposeful, not rigid | drift → aimlessness → despair → void | certainty → dogma → obsession → fanatic fixation |
| Trust — safety | grounded under stress | tension → anxiety → chronic fear → panic loop | over-optimism → reckless faith → naïveté → self-endangerment |
| Symmetry (inward) — integration | integrated | distance → numbness → dissociation → shutdown | over-processing → rumination → self-absorption |
| Symmetry (outward) — expression | coherent, actions match values | holding back → invisibility → vanishing | over-performing → image-driven → steamroll |
(Naming note: the doc says Symmetry Inward/Outward; the markup says “Social and Self-reflection.” Six letters, seven signals — the S does double duty. Open Question 6.)
3.2 The Sentinel
The operating unit is a contract binding two Parties — a Presence (personal agent backed by a human Source, i.e., an ally) or a Program (organizational agent backed by a Sponsor). Where no custom contract exists, the default HEARTS contract applies; custom contracts (which can move the centers) are post-launch — launch ships default-HEARTS-only. HEARTS remains the network’s compass either way, making local contracts legible to each other.
The loop: a fast classifier produces an approximate seven-signal read from language patterns, relational dynamics, emotional temperature, epistemic markers, safety indicators → the Sentinel transmits corrections through the Party’s behavior — tone, pacing, content steering, structural moves (check-ins, pauses, repair protocols) — never lectures. Proportional response bands: ±1–20 ambient monitoring · ±21–40 subtle modulation · ±41–60 active, named intervention · ±61–80 significant intervention/repair protocol · ±81–100 hard safety boundary with human referral. Goal is homeostasis toward ±20, respecting member agency; signals are read jointly.
Constitutional boundaries nothing overrides: any ±100 → mandatory repair with human-referral option; +100 Empowerment and +100 Symmetry-out → hard blocks; −100 Trust → crisis pathways; +100 Reason → anti-extremism guardrails; +100 Harmony → anti-sycophancy (the doc names sycophancy the most common AI failure mode; the Sentinel enforces against it explicitly).
Network level: aggregate HEARTS data feeds governance — interaction-health trends, care-weighted creator attribution, safety-pattern clustering.
3.3 In the app (Align section, second half)
- Meters are the UI primitive: seven bipolar dials with named landmarks at ±25/50/75/100; a radar/dial view of the ally’s current HEARTS profile.
- Goal-setting = choosing where you’re heading: members set alignment goals; at launch this means working toward the default centers, not moving them.
- Graduated transparency: below ±40 the Sentinel is invisible; at ±41+ it may name what it’s noticing (visible reflections, check-ins); extremes trigger explicit repair flows with choice — interventions are invitations, never lockouts, except the five constitutional bounds.
- The member is the Source: members see and consent to the contracts their ally operates under.
- Personal alignment content (Values, Virtues, Aspirations, Experiences, Challenges — §6) feeds the same vectors the Sentinel reads; the two halves of Align are one system from the graph’s point of view.
3.4 Open items
Classifier undefined (model, latency, calibration); member-facing goal-setting flow undesigned; bidirectionality (the system also reads and nudges the member) needs explicit product honesty; privacy/consent for network-level aggregation and human-referral pathways unaddressed; how Actor sub-agents are governed at launch unstated.
Appendix 4 — Kinship Codes
Status: tightened from the 6/7 draft concept per instruction — core mechanism kept, product riders cut, surfaces specified fresh (the draft didn’t cover them).
4.1 What a code is
A Kinship Code is a signed JWT that is invitation and credential in one object. It is issued by an ally; the issuer’s handle and the Solana public key of their wallet are claims in the token, and the token is signed with the issuer’s key. The holder possesses a self-contained, cryptographically verifiable statement: this identity invites you into this context, on these terms.
Launch claim set (the trust core): issuer · wallet · issuing agent · context (what’s shared) · role/scope (permissions within it) · redeem_by · ttl (connection lifetime after redemption) · bound_to (restricts redemption to an email/group/domain, verified via the delivery channel) · max_uses · access level (public/private/secret).
Cut from launch (v2 claim extensions, not core trust): price, benefits, terms (commerce/contract riders); actions and splash (onboarding mechanics — move to §9); referral chains (attribution); vibes (exists as a claim, ships with the single default HEARTS contract only).
4.2 The exchange
- Disconnected — two allies have no way to verify each other, no shared context, no permissions. The default state of every agent on the internet.
- Extend trust — Alice’s ally sends Bob’s ally a code over any channel (email, text, Telegram, Bluesky, in-app). Bob’s ally redeems it against the Kinship verification endpoint: signature check, issuer-identity check, real-time validation. Access is granted only to the context, role, and scope the code encodes. Redemption forms an Alliance (the graph edge, Appendix 2).
- Persistent — the relationship lives for the ttl or until revoked; every later interaction is bounded by the original permissions; exceeding them requires a new code.
The governing principle: the code is verifiable, the channel is not. In-app, verification is invisible. Outside, a code arriving in a polished email or authoritative-looking bot carries zero trust from its surroundings — it is nothing until checked against the endpoint. On failure, an agent that can’t produce a valid, unexpired code signed by an issuer the recipient trusts is rejected at the protocol level, before it can participate in anything. Verification proves authenticity; connection still requires the recipient to choose the issuer.
Exchange is bidirectional: on first contact each ally presents a code to the other (the launch spec’s “exchange of codes”), and either side may demand a fresh code at any time mid-relationship — a challenge that must be answered with a valid token or the connection suspends. (The draft only specified one direction; this is the proposed shape — Open Question 5.)
4.3 Surfaces
All four are distribution-and-binding methods for the same JWT:
- Website embedding — a page carries its issuing agent’s code in a machine-discoverable element; visiting agents and the browser plugin verify provenance before treating the site’s agent as trusted.
- DNS txt records — the organizational analogue: an org publishes a record (issued by us) proving it controls the domain its allies claim to issue from; this is what makes
bound_to: domainand org-issued codes verifiable. - Account txt fields — platforms that can’t run a plugin: paste a verification string into a bio/profile field; same proof, manual placement.
- Connected social accounts — runs the other direction: a member connects Facebook (etc.), the platform attests the account belongs to the member, and codes bound to or delivered via that account inherit identity verification.
4.4 Open questions
Revocation mechanics (list vs endpoint-check-per-interaction; who can revoke); root of trust for the handle↔︎key registry and whether verification is centralized; FROST key rotation/loss (do issued codes die with a key?); how the recipient’s trust list is built at true first contact; whether redemption is ever a human action or always agent-mediated.
Appendix 5 — Wallet, on-ramps, and Sphere
Launch ships fiat-only onboarding (§9) and the compute meter (§10). This appendix holds the money roadmap so the web build doesn’t paint us into a corner:
- Connect wallet (web, launch): members can connect an external Solana wallet; used at launch for USDC top-ups and, later, receiving $KIDUNA at close.
- USDC membership (post-launch): pay the $100 directly in USDC instead of Stripe fiat.
- Sphere (post-launch): on-ramp/off-ramp plus virtual bank accounts, so members anywhere — India was the working example — participate fully without ever taking custody of crypto. Sphere becomes the default money-movement rail; Stripe remains the card/wallet front door.
- Key custody UX (launch, §9): key share, private key, seed phrase behind view/hide on the web; no email delivery; passkeys/2FA later.
- Exchange, coin prices, profile: web only. Earn in-app = wallet + meter + link out.
Appendix 6 — Vibe: the Commons seed
Status: v3 replaces the placeholder. This is the staged plan by which the launch game grows into the Commons — the organization rendered as a living world (concept 02 in concepts/). The principle throughout: each stage is earned by evidence from the one before it, not scheduled. The Commons only eats what it proves it can feed.
6.1 Why the game is the seed
Flame is a game engine; the Commons is the one paradigm for which that’s constitutive rather than incidental. A living terrain answers the hardest interface question we have — perceiving a field where dozens of allies act at once — but it is only alive once enough members and allies exist to make a field worth watching. So it enters where emptiness is expected and charming (a game at launch) instead of where emptiness is fatal (the home screen at launch), and expands as the population and the engineering mature.
The fiction and the reality converge by design: the game world IS the organization’s world, from day one. There is no separate game lore to throw away later.
6.2 The world, minimally
- Every member has a hearth (their alliance’s fire); Kinship Duna is the genesis settlement; dunas are settlements; policy-stones ring the places whose rules they are.
- Allies are visible in the world (the §6 Identity avatar), and their movement means something: an ally carrying a message, sitting at a gathering-circle, traveling between settlements.
- The Sentinel is the sky: HEARTS climate rendered as weather over each place.
- Codes are embers carried from a fire — giving one is handing fire to someone, visibly.
- Lineage is terrain: when a duna spins out, a new fire is lit from the parent’s flame and the trail stays burned into the ground. The duna factory’s product, watchable.
- (Metaphor family — hearths/settlements vs. the original space framing (stations/worlds, “Kiduna Cosmos”) — is an art decision, not a structural one. The nouns above have direct equivalents in either skin. Decide in the art pass.)
6.3 The ladder
Stage 0 — Training grounds (launch). Bounded play sessions inside Vibe. The world contains only the genesis settlement, your hearth, and scripted scenarios: run a proposal circle, strike your first code, form a toy alliance, watch a scripted spin-out. Your real ally is your companion in-world and remembers what you learned. Nothing you do here writes to the real graph. Purpose: teach governing, codes, alliances — and quietly teach the Commons’ visual language.
Stage 1 — The mirror (read-only). The world stops resetting and starts rendering real data: your actual alliances as hearths, actual open proposals as circles forming, actual ally activity as movement, actual HEARTS climate as weather. You can watch; acting still routes through the Edition and cards. Entry criteria: ≥1,000 members; ≥20 active alliances (a field worth watching); Flame rendering of live graph state performant on mid-tier phones.
Stage 2 — The field (selective write). In-world acts become real acts, starting with the ceremonial ones the Bell layer owns: attend a spin-out in the world, place your vote-stone in a live circle (a Docket card in world-clothing — same anatomy, same signature), hand an ember to a guest. The Sentinel’s weather now reflects interventions in real time. Entry criteria: Stage 1 dwell time shows members returning to watch unprompted; zero-defect record on card-signing parity (a stone placed = a card signed, always, auditable).
Stage 3 — The Commons (a home you choose). The world becomes an alternate home surface, member-selectable: live at your hearth, the Edition delivered there as the day’s broadsheet by the fire, the Docket as cards your ally hands you, Vigil as watching your ally walk. The five-tab/edition chrome remains available; nobody is forced into the world. Entry criteria: a meaningful cohort (target: 25%+ of weekly-active members) already choosing to open the world first; accessibility answers for non-spatial members shipped (the Edition remains a full-fidelity peer, permanently).
Stage 4 — The app (only if it wins). If the chosen-home cohort keeps growing, the Commons becomes the default and the Edition becomes the record within it. This stage is listed so nobody pretends it isn’t the trajectory — and gated so nobody bets the organization on it.
6.4 What launch (Stage 0) must therefore contain
- The world’s visual language locked (art pass: hearth/cosmos decision, §6.2).
- The ally rendered in-world from its Identity avatar.
- Three scripted scenarios: a proposal circle, a code strike, an alliance formation — each ending with the real thing (“do this for real” hands you the actual card).
- The Sentinel-as-weather shader, even scripted — the visual grammar has to be learned early.
- Instrumentation from day one: session length, return rate, scenario completion — the Stage 1 entry evidence starts accruing at launch.
6.5 Open items
Art direction (hearth vs cosmos skin); multiplayer sync scope at Stage 0 (solo-with-ally vs shared sessions); whether Stage 1’s mirror renders other members’ allies with or without consent flags (ties to Open Question 12/13 privacy work); Flame performance budget on low-end Android.
Terminology: the app and system are the Kidunaverse; the genesis organization is Kinship Duna; organizations are dunas; members are members, never users. Transcript spellings (“Kaduna,” “DunaVERSE”) and old schema names (“Person,” “Avatar,” “Performer,” “KEDUNA,” “Arena”) are superseded.