Digital Twin — A Partner With Standing

What the Digital Twin is

The Digital Twin is not a separate agent and not a persona file. It is the same AI Partner engine, pointed at you as a partner with standing rather than at a task queue. It adds a layer of mechanisms that carry a relationship on top of ordinary chat and goal execution:

Mechanism	What it gives the twin	File / surface that drives it
Charter	Standing to refuse, to confront, and to earn autonomy	CHARTER.md
Constitutional memory	Founding commitments and corrections that are never summarised away, however old they get	Its permanent record
Positions and the right to dissent	Evidence-backed claims about you that it will argue from	Its Positions, each dated and revisable
Confrontation loop	A scheduled, evidence-gated challenge when your activity drifts from your goals	GOALS.md + CHARTER.md
Earned delegation	The right to act unasked — graduated per action class by clean approvals	CHARTER.md + approvals ledger

The founding principle is deliberate: the twin has no name and no "voice." A name would make it a costume. It is invoked by using AI Partner normally — the twin behaviors are ambient. See How you invoke it.

---

The workspace files, and who reads them

Every user's identity and relationship live in plain Markdown files in their own workspace. On a single-user install that is the base workspace; on a multi-user VPS each user has their own copy (see Multi-user on a VPS).

File	Belongs to	Read by	Purpose
SOUL.md	The agent	Every chat + goal turn	The agent's identity, character, work standards. Not your personal facts.
USER.md	You	Every chat + goal turn (as [USER CONTEXT])	The single source of truth for who you are — your name, role, stack, preferences.
CHARTER.md	The partnership	Before every confrontation and every delegated action — picked up the moment you save it	Confrontation domains, resurface policy, delegated authority, founding episode.
GOALS.md	You	Weekly goal review + twin confrontation	Your active/paused long-horizon goals ("arcs").
HEARTBEAT.md	The agent	Every heartbeat tick	Standing proactive tasks (briefings, scans). Distinct from the twin's charter-driven schedule.
AUTHORITY.md	You	Every action the agent takes for you	Allow / draft-and-ask / block rules; always wins over earned delegation (instant kill switch).

Your name lives in USER.md, not SOUL.md. USER.md is injected into every prompt as [USER CONTEXT]. If you edit your name and the agent still uses the old one, you almost certainly edited the wrong workspace's copy — see Troubleshooting.

---

Enabling and configuring

The twin is on by default. Two switches govern it, in your instance settings:

Switch	Default	Effect
Digital Twin	on	The master switch. Off disables every twin behaviour, including the relationship context it normally carries into each conversation.
Earned delegation	on	An organisation-wide kill switch for autonomy only (administrators hold this one). Off blocks all earned autonomy while leaving memory and confrontation working.

To use the twin to its full potential you configure CHARTER.md. It takes effect the moment you save — nothing to restart:

## Granted Confrontation Domains
# The twin may challenge you ONLY in these domains, and only with >= `evidence`
# distinct observations, at most once per week overall. Empty = never confronts.
- domain: stated_goals_vs_activity + evidence: 3
- domain: project_build_arcs + evidence: 3
- domain: health_habits + evidence: 3

## Resurface Policy
- suppression_cooloff_days: 14
- max_suppressions_per_arc: 3
- third_suppression: present_all_three   # third back-off shows all three, then retires the arc

## Delegated Authority
# Action classes the twin may EARN after `graduate_after` clean approvals.
# apply: absent_only = used only when you're unreachable. Not listed = never eligible.
- action_class: send_telegram_dm + graduate_after: 5 + apply: absent_only
- action_class: reply_email + graduate_after: 5 + apply: absent_only

## Founding Episode
<!-- Paste your founding-conversation document here. Ingested once as the twin's
     first constitutional memory. Leave empty to skip. -->

Removing a domain removes the twin's standing in it immediately. An empty Granted Confrontation Domains section means the twin never confronts you at all. Deny-by-default in both directions: a domain not listed grants no standing; an action class not listed is never delegable.

To actually exercise the full loop you also need:

1. A connected messaging channel — Telegram, Discord, or Slack (Settings → Messaging). This is how confrontations and daily digests reach you.
2. A populated GOALS.md — the source of the "arcs" the twin holds you to.

---

How you invoke it

You don't summon the twin — you just talk to AI Partner. When twinConnectEnabled is on, its relationship memory, open threads, and held positions are injected into every system prompt, so the agent will disagree with you, cite dated evidence, and hold questions open across sessions on its own.

The places you deliberately engage the twin layer:

1. 1
   Chat normally

   Speak to AI Partner as usual. It records corrections, forms positions about you, and opens/resolves threads via its twin_record tool as the conversation unfolds — you never call the tool yourself.

2. 2
   Amend the charter by intent

   Say "I want to amend the charter" in chat. The twin restates the current clause, the proposed clause, and the consequence, then asks for explicit confirmation before editing CHARTER.md. (Direct edits to the file also work and hot-reload — the ceremony just makes constitutional changes deliberate.)

3. 3
   Answer confrontations

   When your activity drifts from your goals, the twin delivers one charter-gated challenge over your messaging channel (and in-app) with engage / adjust / back_off buttons. A "back off" is obeyed and remembered; silence or timeout is never treated as backing off.

4. 4
   Use the "Your Twin" panel

   Open the Proactive view → Your Twin. From there you can answer pending asks in-app, resolve open threads, revoke an earned delegation instantly, and read the twin's positions, action feed, and charter.

---

Multi-user on a VPS

On a multi-user instance every user is an isolated tenant. This is the setup you use when hosting AI Partner on a VPS for a team.

Per-user isolation

Every user on the instance gets their own workspace, seeded with the full template set (including CHARTER.md, USER.md, SOUL.md, GOALS.md):

Your own workspace
├── SOUL.md      ├── USER.md
├── CHARTER.md   ├── GOALS.md
├── AUTHORITY.md └── HEARTBEAT.md

You reach yours through the Workspace browser in the sidebar, which always opens your copy — never a shared or template one.

Everything the twin knows is scoped to the login:

• Chat and goal prompts read that user's own SOUL.md / USER.md — so a user editing their USER.md changes their agent, and no one else's.
• Confrontations and digests arrive on that user's own connected channel — never crossed between people.
• Constitutional memory, positions, open threads, back-offs and earned delegations belong to that login alone.

Admin governance — conduct, never content

On a shared instance, administrators govern twins without ever seeing their content. What they can do is bounded deliberately: see which users have an active twin and what it has done under delegation, suspend a twin's earned autonomy, and switch delegation off across the organisation.

What they can never see is everything that makes it a relationship — a twin's memories, its positions, the text of a confrontation, why it backed off, or your goals.

And the asymmetry is the point: an administrator may freeze an autonomy, but only you can re-earn it. Actions taken in the organisation's name are the organisation's business; the relationship is yours.

---

Get the most out of it — an owner's walkthrough

Do these once and the twin moves from "on" to "actually a partner":

1. 1
   Make USER.md real

   Put your actual name, role, and working style in your USER.md. This is the single source of truth for who you are and is read on every turn.

2. 2
   Grant confrontation standing

   In CHARTER.md, list the domains you want to be challenged on (e.g. stated_goals_vs_activity). Start with an evidence of 3 so the twin only speaks when it has real grounds.

3. 3
   Give it goals to hold you to

   Populate GOALS.md with your genuine active goals. The twin compares these against your actual weekly activity — no goals, nothing to confront.

4. 4
   Connect a channel

   Connect Telegram (Settings → Messaging). This is where the weekly confrontation and the daily "while you were away" digest arrive.

5. 5
   Let it earn delegation

   List a low-risk action class in CHARTER.md Delegated Authority (e.g. send_telegram_dm, absent_only). Approve its drafts cleanly a few times; after graduate_after clean approvals it graduates to acting unasked — and one edit or skip revokes it instantly.

6. 6
   Correct it, and watch it stick

   When it's wrong about you, say so. Corrections become permanent constitutional memory — a corrected mistake never repeats — and revise the underlying position out loud, with history.

7. 7
   Optional: write a founding episode

   Paste the conversation that defines the partnership into the ## Founding Episode section of CHARTER.md. It is ingested once as the twin's first constitutional memory — the record of how, and why, this partnership began.

---

Troubleshooting: "my name isn't picked up"

The name the agent uses comes from USER.md (injected as [USER CONTEXT]). Everything below is fixable from inside the app — no server access needed. If a name change doesn't take:

1. Edit USER.md in the in-app Workspace browser. Open Workspace in the app and edit USER.md there — that editor always points at your own copy, on any install. The change applies from your next message.
2. A stale name in SOUL.md. Workspaces set up on older versions may still carry your name inside SOUL.md (the agent's identity file). Open SOUL.md in the same Workspace browser and remove any ## User / "You work primarily with…" line so USER.md is the single source.
3. Memory recall. If you told the agent a different name in earlier conversations, it may recall it. Correct it in chat ("my name is X, not Y") and the correction becomes permanent.

Rule of thumb: SOUL.md = the agent. USER.md = you. One fact, one home.