@minca/core 0.1.17 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/README.md +2 -1
  2. package/dist/files/space-files.d.ts +2 -2
  3. package/dist/files/space-files.d.ts.map +1 -1
  4. package/dist/files/space-files.js +7 -5
  5. package/dist/files/space-files.js.map +1 -1
  6. package/dist/inbox/names.d.ts +1 -1
  7. package/dist/inbox/names.js +1 -1
  8. package/dist/index.d.ts +3 -1
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +2 -0
  11. package/dist/index.js.map +1 -1
  12. package/dist/node/actions.d.ts +3 -0
  13. package/dist/node/actions.d.ts.map +1 -1
  14. package/dist/node/actions.js.map +1 -1
  15. package/dist/node/api.d.ts +1 -0
  16. package/dist/node/api.d.ts.map +1 -1
  17. package/dist/node/api.js +1 -0
  18. package/dist/node/api.js.map +1 -1
  19. package/dist/node/carrier.js +1 -1
  20. package/dist/node/carrier.js.map +1 -1
  21. package/dist/node/index.d.ts +1 -1
  22. package/dist/node/index.d.ts.map +1 -1
  23. package/dist/node/node-contacts.d.ts.map +1 -1
  24. package/dist/node/node-contacts.js +1 -0
  25. package/dist/node/node-contacts.js.map +1 -1
  26. package/dist/node/node-records.d.ts.map +1 -1
  27. package/dist/node/node-records.js +6 -1
  28. package/dist/node/node-records.js.map +1 -1
  29. package/dist/node/node.d.ts.map +1 -1
  30. package/dist/node/node.js +13 -1
  31. package/dist/node/node.js.map +1 -1
  32. package/dist/node/remote.d.ts.map +1 -1
  33. package/dist/node/remote.js +7 -1
  34. package/dist/node/remote.js.map +1 -1
  35. package/dist/node/space-runtime.d.ts +5 -3
  36. package/dist/node/space-runtime.d.ts.map +1 -1
  37. package/dist/node/space-runtime.js +3 -1
  38. package/dist/node/space-runtime.js.map +1 -1
  39. package/dist/node/types.d.ts +112 -36
  40. package/dist/node/types.d.ts.map +1 -1
  41. package/dist/node/watch-notifications.d.ts +6 -0
  42. package/dist/node/watch-notifications.d.ts.map +1 -1
  43. package/dist/node/watch-notifications.js +47 -9
  44. package/dist/node/watch-notifications.js.map +1 -1
  45. package/dist/query/types.d.ts +1 -0
  46. package/dist/query/types.d.ts.map +1 -1
  47. package/dist/query/types.js.map +1 -1
  48. package/dist/records/contract-builder.d.ts +22 -6
  49. package/dist/records/contract-builder.d.ts.map +1 -1
  50. package/dist/records/contract-builder.js.map +1 -1
  51. package/dist/schemas/automations.d.ts +6 -2
  52. package/dist/schemas/automations.d.ts.map +1 -1
  53. package/dist/schemas/automations.js.map +1 -1
  54. package/dist/schemas/connectors.d.ts +4 -3
  55. package/dist/schemas/connectors.d.ts.map +1 -1
  56. package/dist/schemas/connectors.js +4 -3
  57. package/dist/schemas/connectors.js.map +1 -1
  58. package/dist/schemas/library/media.js +1 -1
  59. package/dist/schemas/library/media.js.map +1 -1
  60. package/dist/session/account-hint.d.ts +2 -2
  61. package/dist/session/account-hint.d.ts.map +1 -1
  62. package/dist/session/account-hint.js +3 -3
  63. package/dist/session/account-hint.js.map +1 -1
  64. package/dist/session/auth.d.ts +7 -3
  65. package/dist/session/auth.d.ts.map +1 -1
  66. package/dist/session/auth.js.map +1 -1
  67. package/dist/session/connection.d.ts +18 -0
  68. package/dist/session/connection.d.ts.map +1 -1
  69. package/dist/session/connection.js +11 -0
  70. package/dist/session/connection.js.map +1 -1
  71. package/dist/session/index.d.ts +2 -2
  72. package/dist/session/index.d.ts.map +1 -1
  73. package/dist/session/index.js +2 -2
  74. package/dist/session/index.js.map +1 -1
  75. package/dist/storage/blob-store.d.ts +3 -0
  76. package/dist/storage/blob-store.d.ts.map +1 -1
  77. package/dist/types.d.ts +11 -2
  78. package/dist/types.d.ts.map +1 -1
  79. package/dist/types.js.map +1 -1
  80. package/docs/README.md +86 -93
  81. package/docs/actions.md +213 -152
  82. package/docs/agents.md +198 -167
  83. package/docs/automations.md +296 -204
  84. package/docs/blueprints-and-guides.md +405 -311
  85. package/docs/bots.md +208 -134
  86. package/docs/building-an-app.md +86 -159
  87. package/docs/collections.md +248 -328
  88. package/docs/computed.md +112 -89
  89. package/docs/contacts.md +151 -112
  90. package/docs/contracts.md +299 -120
  91. package/docs/direct-messages.md +80 -65
  92. package/docs/inbox.md +138 -93
  93. package/docs/node.md +1081 -996
  94. package/docs/permissions.md +142 -0
  95. package/docs/proposing-collections.md +74 -55
  96. package/docs/query-format.md +150 -126
  97. package/docs/records-and-queries.md +205 -126
  98. package/docs/sign-in.md +487 -416
  99. package/docs/spaces.md +261 -246
  100. package/docs/standard-library.md +487 -526
  101. package/docs/storage.md +325 -348
  102. package/docs/usernames.md +164 -97
  103. package/docs/warrants.md +100 -67
  104. package/package.json +1 -6
  105. package/dist/elements/auth-styles.d.ts +0 -18
  106. package/dist/elements/auth-styles.d.ts.map +0 -1
  107. package/dist/elements/auth-styles.js +0 -206
  108. package/dist/elements/auth-styles.js.map +0 -1
  109. package/dist/elements/dom.d.ts +0 -29
  110. package/dist/elements/dom.d.ts.map +0 -1
  111. package/dist/elements/dom.js +0 -91
  112. package/dist/elements/dom.js.map +0 -1
  113. package/dist/elements/index.d.ts +0 -13
  114. package/dist/elements/index.d.ts.map +0 -1
  115. package/dist/elements/index.js +0 -11
  116. package/dist/elements/index.js.map +0 -1
  117. package/dist/elements/minca-auth.d.ts +0 -55
  118. package/dist/elements/minca-auth.d.ts.map +0 -1
  119. package/dist/elements/minca-auth.js +0 -768
  120. package/dist/elements/minca-auth.js.map +0 -1
package/docs/agents.md CHANGED
@@ -1,198 +1,229 @@
1
1
  # Agents
2
2
 
3
- An agent reads and writes as the person, with a note from their account that
4
- every peer checks. The protocol doesn't know it is an agent: it is a program
5
- that asked for a note that grants writing records and nothing more
6
- (`/record`), so every peer refuses it defining collections, changing who
7
- may do what, or writing for the account ([spec 01 §8](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md)).
8
- What it writes counts as the person's, and carries `recordsOnly: true`
9
- everywhere, which apps may show (the example app says "via agent"). It never
10
- gets the seed.
11
-
12
- An agent that is its own user, such as a community's bot, is an account of
13
- its own instead (see Bots, below).
3
+ An agent can read and write in a person's spaces as them. It might be Claude
4
+ in a chat app, a coding agent in your terminal, or a program you write. This
5
+ page shows how to connect one, and what it may do once it is in.
14
6
 
15
- ## Every operation, described once
16
-
17
- Every node operation is in `NODE_ACTIONS`: a name, a sentence and a JSON
18
- Schema for its input. The CLI, the MCP server and the browser's WebMCP tools
19
- are all generated from it.
7
+ ## From a chat app
20
8
 
21
- ```typescript
22
- import { NODE_ACTIONS, runAction } from '@minca/core';
9
+ The simplest way is Minca's MCP service. Add it to your chat app by its
10
+ address:
23
11
 
24
- await runAction(node, 'records_put', { space, collection: 'app.todo.item', body: { text: 'milk' } });
12
+ ```bash
13
+ claude mcp add --transport http minca https://mcp.minca.social/mcp
25
14
  ```
26
15
 
27
- `records_query` takes the same plain-JSON query as `node.records.query`
28
- ([records-and-queries.md](records-and-queries.md)).
16
+ [minca.social/mcp](https://minca.social/mcp) has one-click links for Claude
17
+ and Cursor. The app opens a page where you sign in at your account home and
18
+ pick the spaces it may use, up to 8. The access lasts 30 days. Then its
19
+ tools arrive, and the chat app's own
20
+ model does the thinking.
29
21
 
30
- ## Connecting an agent to someone's account
22
+ How the service works, and how to run your own, is under
23
+ [The MCP service](#the-mcp-service) below.
31
24
 
32
- From `@minca/cli`, the `minca` command:
25
+ ## From a terminal
26
+
27
+ An agent with a shell, like Claude Code, Codex or Cursor's agent, uses
28
+ Minca through the `minca` command. Connect it once:
33
29
 
34
30
  ```bash
35
31
  npx @minca/cli connect
36
32
  ```
37
33
 
38
- It makes a key for this computer's agent and opens the person's account home
39
- in the browser, where they sign in, or make an account, and allow it. The
40
- home then shows six digits, which the person types into the terminal: the
41
- agent keeps its note only once they match. From then on every `minca`
42
- command on spaces or records on that computer runs as the agent unless an
43
- account is named
44
- (`--account`): an agent with a shell (Claude Code, Codex, Cursor's agent)
45
- uses Minca through the CLI, and what it writes shows "via agent". Each
46
- command catches up with the space's always-on nodes before it acts, and
47
- refuses when it can't, as the MCP service does
48
- ([the CLI's README](https://github.com/leifriksheim/minca/blob/main/packages/cli/README.md#agents)).
49
- A chat app with no shell connects to Minca's MCP service instead (below).
50
-
51
- `minca agent` runs the same agent without a chat client: it chats in the
52
- terminal and thinks with the person's own Anthropic API key, offering the model
53
- the same tools. See `packages/cli/README.md`.
54
-
55
- ## Connecting a chat app
56
-
57
- Minca's MCP service (`minca mcp-server`) offers the same tools to chat apps
58
- over the network: an MCP endpoint at `/mcp`, signed in with OAuth. The
59
- consent page the app opens is an app like any other to the account home: it
60
- makes a key in the browser and asks for a note with `connectToHome`, records
61
- only, in the spaces the person picks, then hands the key and the note to the
62
- service, which checks them (`checkGrant(grant, did, { recordsOnly: true })`,
63
- and that the key's halves belong together) and keeps them sealed under a key
64
- only the app's access token carries. Each call starts a node from what the token opens
65
- (`startGrantedAgent`), in memory, reaching the always-on nodes and relays its
66
- invites and spaces name at public addresses only, and the service's own
67
- (`network.reach`, [node.md](node.md)). A write is done once the space's keepers have it
68
- (`spaces.kept`), and the key's places, the one thing kept, outlast the node. Nothing new goes over the wire between the home and the
69
- page. See `packages/cli/README.md`, Agents.
34
+ Your browser opens your account home. Sign in, or make an account, and allow
35
+ it. The home shows six digits to type into the terminal, and the agent keeps
36
+ its access only once they match.
70
37
 
71
- ## Connecting at your account home
38
+ From then on, every `minca spaces …` and `minca records …` command on this
39
+ computer runs as the agent, unless `--account` names an account. Tell your
40
+ agent to start with `minca help`. Each command catches up with the space's
41
+ always-on nodes before it acts, and refuses when it can't.
72
42
 
73
- The code, the channel it opens and the messages the two sides trade are
74
- protocol, and know nothing of agents
75
- ([spec 06 §3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
76
- The library's two sides are `connectWithCode` (the program) and
77
- `receiveConnectCode` (the account home).
43
+ The details are in [the CLI's README](https://github.com/leifriksheim/minca/blob/main/packages/cli/README.md#agents).
78
44
 
79
- - `newConnectCode()` makes a code, and `connectCodeUrl(home, code)` the link
80
- to open: `https://home.minca.social/connect#mc_…`.
81
- - `connectWithCode({ home, code, key, name, network, check, onWaiting? })`
82
- waits in the code's room, signs the proof once it learns the home's origin
83
- (`keyProof(key, { via: 'code', recordsOnly: true, origin })`), tells
84
- `onWaiting({ origin })` when the home has heard, and keeps only a
85
- records-only note made out to its key, once `check(matches)` has had the
86
- person give the six digits the home showed.
87
- - `receiveConnectCode({ code, relays, onAnswered? })`, on the home's connect
88
- page, answers the program and gives back the same `IncomingRequest` an
89
- app's popup does: records only, in the whole account, for 30 days, with
90
- `check`, the six digits to show.
91
- `connectCodeIn(location.hash)` finds the code. `answerConnectCode` is the
92
- same exchange without the request around it.
93
-
94
- What the reference sides add:
45
+ ## Helping you build an app
95
46
 
96
- - The terminal asks which account home to open, with home.minca.social, or
97
- the one it connected at last, filled in so Enter takes it.
98
- `--account-home` or `MINCA_ACCOUNT_HOME` names it ahead. The MCP server's
99
- connect tool takes no home: the model never chooses where the person signs
100
- in. Anywhere nothing can be asked, it uses the usual one.
101
- - It opens the link in the browser, and shows it only when none opens (a
102
- server, a terminal over SSH), since whoever else holds it could answer as
103
- the home. The link works from any device.
104
- - `connectWithCode` asks only the home it opened, and keeps that home in the
105
- grant, whatever the answer names; it prints the account's DID beside its
106
- name.
107
- - The home (`apps/home/src/components/ConnectPage.tsx`) takes the code out
108
- of the address bar, shows the program's name and says to allow it only if
109
- the person started it just now. Once answered it says so, and the tab can
110
- be closed. When no program asks within a minute, it says the link was
111
- used or has run out.
112
- - The terminal waits 10 minutes for the home to open, since the person may
113
- make an account first, then 30 minutes for the answer. It checks the grant
114
- with `checkGrant(grant, did, { recordsOnly: true })` before keeping it, and
115
- again each time it starts, and says whose account it joined.
116
- - The terminal makes a new key for each connect. Connecting again, after a
117
- disconnect or to renew, gives a new key and note; a running `minca agent`
118
- takes them up without a restart. The earlier connection stays in the
119
- account home until it is disconnected there, and nothing can use it: its
120
- key is gone from the computer.
121
- - An app only says how: "Connect an agent" in the example app shows the
122
- command (`apps/example/src/components/ConnectAgent.tsx`).
123
-
124
- _Source: `packages/core/src/session/connect-code.ts`, `packages/cli/src/agent.ts` (`connectAgent`, `openInBrowser`, `startAgentNode`, `reloadOnConnect`), `packages/cli/src/main.ts` (`chooseAccountHome`), `apps/home/src/components/ConnectPage.tsx`. Tests: `packages/core/tests/connect-code.test.ts`, `packages/core/tests/records-only.test.ts` ("a program connected by code, through the account home"), `packages/cli/tests/agent-reconnect.test.ts`, `packages/cli/tests/cli-agent.test.ts`._
125
-
126
- ## Tools an agent gets
127
-
128
- `node_info`, `spaces_list`, `spaces_status`, `spaces_preview_invite`, `spaces_access`, `spaces_profiles`,
129
- `collections_list`, `records_query`, `records_get`,
130
- `records_linked`, `records_history`, `records_can`, `records_put`,
131
- `records_update`, `records_delete`, `activity_set` (what it is doing, for
132
- people to see), and for new collections: `collections_standard`,
133
- `collections_proposals`, `collections_propose`. A bot, an account of its own, also gets
134
- `direct_list` and `direct_send`: it holds its own member key, and an agent
135
- isn't given the person's ([direct messages](direct-messages.md)).
136
-
137
- To make something new, an agent proposes the collections it needs
138
- (`collections_propose`), the same way a person whose role can't define
139
- collections does. Someone who may reads what it would do and applies it.
140
- What else an app keeps, such as a screen or what is worth hearing about, is
141
- the app's: `collections_list` points at the guides a space's apps wrote
142
- (`std.guide`), which say how to propose one there. See
143
- [blueprints and guides](blueprints-and-guides.md).
144
-
145
- ## Automations
146
-
147
- An agent that runs by itself (`minca agent`) also runs the person's
148
- automations ([automations.md](automations.md)), and does what those that ask
149
- it say: when some records come to be a certain way, or at set times. An agent
47
+ These docs ship inside `@minca/core`, matched to the installed version. A
48
+ coding agent in your repository finds them at
49
+ `node_modules/@minca/core/docs/`. One line pointing there in your
50
+ project's `AGENTS.md` or `CLAUDE.md` is enough.
51
+
52
+ ## What an agent may do
53
+
54
+ An agent gets a note from the person's account that lets it write records
55
+ and nothing more. It never gets the account's keys. Every peer refuses an
56
+ agent that tries to define collections, change who may do what, or write for
57
+ the account.
58
+
59
+ What it writes counts as the person's. Each record carries
60
+ `recordsOnly: true`, which apps may show. The example app says "via agent".
61
+
62
+ The note's format is in [spec 01 §8](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md).
63
+
64
+ ## The tools
65
+
66
+ An agent gets the same tools from the CLI, the MCP service and WebMCP: the
67
+ node's actions that read spaces and records, write records, say what it is
68
+ doing, and propose collections. Each one, with what it takes, is in
69
+ [the list of actions](https://minca.dev/automations/actions/#the-list).
70
+
71
+ The MCP service leaves out `spaces_preview_invite`, which would have it dial
72
+ addresses a caller chose. `records_query` takes the same JSON query as `node.records.query`
73
+ ([Records and queries](records-and-queries.md)).
74
+
75
+ A bot also gets `direct_list` and `direct_send`. It holds its own member key,
76
+ and an agent isn't given the person's ([Direct messages](direct-messages.md)).
77
+
78
+ ## Making something new
79
+
80
+ An agent can't define collections, so it proposes the ones it needs with
81
+ `collections_propose`. Someone who may define collections reads what the
82
+ proposal would do, and applies it. A person whose role can't define
83
+ collections works the same way.
84
+
85
+ `collections_list` points at the guides a space's apps wrote (`std.guide`),
86
+ which say how they want new things proposed there. See
87
+ [Proposing collections](proposing-collections.md).
88
+
89
+ ## An agent in the terminal: `minca agent`
90
+
91
+ `minca agent` runs the same agent without a chat app. It chats in the
92
+ terminal and thinks with your own Anthropic API key. With
93
+ `--provider openai` it uses any server that speaks OpenAI's Chat Completions,
94
+ including a model on your own machine.
95
+
96
+ It also runs the person's [automations](automations.md): when some records
97
+ come to be a certain way, or at set times, it does what they say. An agent
150
98
  may write an automation when asked, but it runs only once the person has
151
99
  saved it themselves.
152
100
 
153
- `minca agent` can think with Anthropic's models, or with any server that
154
- speaks OpenAI's Chat Completions, including a model on your own machine
155
- (`--provider openai`; see `packages/cli/README.md`).
101
+ See the [CLI's README](https://github.com/leifriksheim/minca/blob/main/packages/cli/README.md).
156
102
 
157
103
  ## Bots
158
104
 
159
- A bot is the same program running as an account of its own
160
- (`minca agent --bot`), which people invite to their spaces as a member. It
161
- writes as itself, is checked against its role like any member, and is
162
- mentioned by the name its account says, like anyone: the one it was made
163
- with, unless its account already says another. It runs the automations that
164
- name it in `by`, of members granted `/std.automation/instruct` in a space. Where a space
165
- keeps `std.profile`, it says it is a bot there with `bot: true`, as soon as
166
- the definition arrives, and where its role may add collections it adds
167
- `std.profile` itself. Apps list bots from that, so a space without it shows
168
- none. See [automations.md](automations.md#who-runs-an-automation)
169
- and [standard-library.md](standard-library.md) (Bots).
170
-
171
- The usual way to have one is to let the host that keeps the community online
172
- run it (`node.hosting.startBot`, [spec 08 §3](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md)):
173
- an admin picks its name and role in the app, the host makes its account and
174
- joins, and the community pays for it as it pays for hosting. The host thinks
175
- with its own model key, within a daily cap per bot, and holds the bot's keys,
176
- so it can read what the bot can read. `minca agent --bot` is the same bot run
177
- by whoever wants to, with their own key.
105
+ A bot is an agent that is its own account. People invite it to their spaces
106
+ as a member. It writes as itself, is checked against its role like any
107
+ member, and is mentioned by its account's name.
108
+
109
+ The usual way to have one is to let the community's host run it
110
+ (`node.hosting.startBot`). An admin picks its name and role in the app, and
111
+ the host makes its account and joins. The community pays for it as it pays
112
+ for hosting. The host thinks with its own model key, within a daily cap per
113
+ bot. It holds the bot's keys, so it can read what the bot can read.
114
+
115
+ `minca agent --bot` runs the same bot yourself, with your own model key.
116
+
117
+ A bot runs the automations that name it in `by`, written by members granted
118
+ `/std.automation/instruct`. Where a space keeps `std.profile`, the bot marks
119
+ itself `bot: true` there as soon as the definition arrives, and adds
120
+ `std.profile` itself where its role may add collections. Apps list bots from
121
+ that, so a space without `std.profile` shows none.
122
+
123
+ See [Bots](bots.md), [who runs an automation](automations.md#who-runs-an-automation)
124
+ and the [standard library](standard-library.md). Hosted bots are in
125
+ [spec 08 §3](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md).
126
+
127
+ ## Every operation, described once
128
+
129
+ Every node operation is in `NODE_ACTIONS`, with a name, a sentence and a JSON
130
+ Schema for its input. The CLI, the MCP service and WebMCP tools are all made
131
+ from it. You can run one by name:
132
+
133
+ ```typescript
134
+ import { runAction } from '@minca/core';
135
+
136
+ await runAction(node, 'records_put', {
137
+ space: space.id,
138
+ collection: 'app.todo.item',
139
+ body: { text: 'milk' },
140
+ });
141
+ ```
142
+
143
+ See [Actions](actions.md).
178
144
 
179
145
  ## In your own code
180
146
 
181
- `node.asAgent({ keys, note })` gives the same node acting as an agent, from a
182
- note that grants records only, issued by the account home. Everything it
183
- writes is signed under that note. A record written under a note that can't
184
- define collections is `recordsOnly: true`; an app that runs what a record
185
- holds, as code, should trust only records without it.
147
+ `node.asAgent({ keys, note })` gives the same node acting as an agent, from
148
+ a records-only note the account home issued. Everything it writes is signed
149
+ under that note, and carries `recordsOnly: true`. An app that runs what a
150
+ record holds as code should trust only records without it.
186
151
 
187
152
  Records don't say which program wrote them, only that its note grants
188
- records only. Naming it would be the program's own word, signed by the account
189
- on its say-so, not a proof, and peers would judge records the same either way;
190
- an app that wants to show it can keep its own list of connected programs by
191
- key, as the account home does.
153
+ records only. A name would be the program's own word, not proof. An app that
154
+ wants to show one can keep its own list of connected programs by key, as the
155
+ account home does.
156
+
157
+ ## The MCP service
158
+
159
+ `minca mcp-server` is the service chat apps connect to. It has an MCP
160
+ endpoint at `/mcp`, and apps sign in with OAuth.
161
+
162
+ The consent page the app opens is an app like any other to the account home.
163
+ It makes a key in the browser and asks for a records-only note in the spaces
164
+ the person picks, with `connectToHome`. It hands the key and note to the
165
+ service. The service checks them with
166
+ `checkGrant(grant, did, { recordsOnly: true })`, and keeps them sealed under
167
+ a key only the app's access token carries.
192
168
 
193
- ## Working on a Minca app with a coding agent
169
+ Each call starts a node in memory from what the token opens
170
+ (`startGrantedAgent`). It reaches only the always-on nodes and relays the
171
+ person's invites and spaces name at public addresses, and the service's own
172
+ (`network.reach`, see [The node](node.md)). A write is done once the space's
173
+ keepers have it (`spaces.kept`). The one thing kept between calls is where
174
+ the key has signed, so the next node doesn't sign at a place it used.
194
175
 
195
- These guides ship inside the package so an agent in your repository can read
196
- them at `node_modules/@minca/core/docs/`, matched to the installed
197
- version. A line in your project's `AGENTS.md` or `CLAUDE.md` pointing there is
198
- enough.
176
+ Nothing new goes over the wire between the home and the page. See
177
+ [the CLI's README](https://github.com/leifriksheim/minca/blob/main/packages/cli/README.md#agents).
178
+
179
+ ## Connecting at your account home
180
+
181
+ `minca connect` uses a one-time code to reach the account home. The code,
182
+ the channel it opens and the messages sent over it are protocol, and know
183
+ nothing of agents ([spec 06 §3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
184
+
185
+ The program's side is `connectWithCode`, and the account home's is
186
+ `receiveConnectCode`:
187
+
188
+ - `newConnectCode()` makes a code, and `connectCodeUrl(home, code)` the link
189
+ to open: `https://home.minca.social/connect#mc_…`.
190
+ - [`connectWithCode`](https://minca.dev/api/session/functions/connectWithCode/)
191
+ waits in the code's room. Once it learns the home's origin, it signs the
192
+ proof (`keyProof(key, { via: 'code', recordsOnly: true, origin })`) and
193
+ calls `onWaiting({ origin })`. It keeps a records-only note made out to its
194
+ key only after `check(matches)` has had the person enter the six digits.
195
+ - [`receiveConnectCode`](https://minca.dev/api/session/functions/receiveConnectCode/) runs on the home's
196
+ connect page. It answers the program and returns the same
197
+ `IncomingRequest` an app's popup does: records only, in the whole account,
198
+ for 30 days, with `check`, the six digits to show.
199
+ - `connectCodeIn(location.hash)` finds the code in the address.
200
+ `answerConnectCode` is the same exchange without the request around it.
201
+
202
+ ### What the CLI and the account home add
203
+
204
+ - The terminal asks which account home to open, with home.minca.social, or
205
+ the one used last, filled in. `--account-home` or `MINCA_ACCOUNT_HOME`
206
+ answers ahead. Where nothing can be asked, it uses the usual one. The MCP
207
+ server's connect tool takes no home, so the model never chooses where the
208
+ person signs in.
209
+ - It opens the link in the browser, and shows it only when no browser opens,
210
+ like on a server or over SSH. Whoever else holds the link could answer as
211
+ the home. The link works from any device.
212
+ - `connectWithCode` asks only the home it opened, and keeps that home in the
213
+ grant, whatever the answer names. It prints the account's DID beside its
214
+ name.
215
+ - The home takes the code out of the address bar and shows the program's name. It says to allow it only if
216
+ the person started it just now. Once answered, it says so and the tab can
217
+ be closed. If no program asks within a minute, it says the link was used
218
+ or has run out.
219
+ - The terminal waits 10 minutes for the home to open, since the person may
220
+ make an account first, then 30 minutes for the answer. It checks the grant
221
+ with `checkGrant(grant, did, { recordsOnly: true })` before keeping it and
222
+ each time it starts, and says whose account it joined.
223
+ - Each connect makes a new key. Connecting again, to renew or after a
224
+ disconnect, gives a new key and note, and a running `minca agent` picks
225
+ them up without a restart. The earlier connection stays in the account
226
+ home until it is disconnected there, but nothing can use it: its key is
227
+ gone from the computer.
228
+ - An app only says how. "Connect an agent" in the example app shows the
229
+ command.