copilotz 1.0.0-rc.44 → 1.0.0-rc.47

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 (235) hide show
  1. package/AGENTS.md +399 -0
  2. package/CHANGELOG.md +108 -0
  3. package/README.md +39 -10
  4. package/hosts/web/palette/palette.d.ts +2 -1
  5. package/hosts/web/palette/palette.js +25 -24
  6. package/hosts/web/palette/state.d.ts +18 -6
  7. package/hosts/web/palette/state.js +8 -0
  8. package/package.json +85 -6
  9. package/plugins/access/contacts/mod.d.ts +3 -1
  10. package/plugins/access/contacts/mod.js +7 -3
  11. package/plugins/access/contacts/views/notes.d.ts +11 -0
  12. package/plugins/access/contacts/views/notes.js +34 -0
  13. package/plugins/access/spaces/actions/member.js +3 -1
  14. package/plugins/access/spaces/collections/member.d.ts +17 -0
  15. package/plugins/access/spaces/collections/member.js +5 -0
  16. package/plugins/access/spaces/contract.d.ts +6 -3
  17. package/plugins/access/spaces/contract.js +2 -2
  18. package/plugins/access/spaces/mod.d.ts +9 -6
  19. package/plugins/access/spaces/mod.js +9 -8
  20. package/plugins/access/spaces/shared/audience.d.ts +51 -0
  21. package/plugins/access/spaces/shared/audience.js +112 -0
  22. package/plugins/access/spaces/shared/can.d.ts +19 -0
  23. package/plugins/access/spaces/shared/can.js +25 -0
  24. package/plugins/access/spaces/shared/labels.d.ts +23 -25
  25. package/plugins/access/spaces/shared/labels.js +70 -86
  26. package/plugins/access/spaces/shared/reach.d.ts +28 -8
  27. package/plugins/access/spaces/shared/reach.js +120 -19
  28. package/plugins/access/spaces/shared/rules.d.ts +3 -2
  29. package/plugins/access/spaces/shared/rules.js +7 -4
  30. package/plugins/access/spaces/shared/seat.d.ts +1 -1
  31. package/plugins/access/spaces/shared/seat.js +9 -3
  32. package/plugins/access/spaces/views/web/words.d.ts +1 -1
  33. package/plugins/agents/chat/actions/approve.js +109 -0
  34. package/plugins/agents/chat/actions/erase.js +5 -9
  35. package/plugins/{compute/computers → agents/chat}/actions/forget-grant.js +1 -1
  36. package/plugins/agents/chat/actions/move.js +13 -19
  37. package/plugins/agents/chat/actions/notes.d.ts +1 -0
  38. package/plugins/agents/chat/actions/notes.js +48 -0
  39. package/plugins/agents/chat/actions/unmark.d.ts +1 -0
  40. package/plugins/agents/chat/actions/unmark.js +100 -0
  41. package/plugins/{compute/computers → agents/chat}/collections/approval.d.ts +116 -47
  42. package/plugins/agents/chat/collections/approval.js +107 -0
  43. package/plugins/agents/chat/collections/file.d.ts +2 -2
  44. package/plugins/{compute/computers → agents/chat}/collections/grant.d.ts +20 -23
  45. package/plugins/{compute/computers → agents/chat}/collections/grant.js +12 -10
  46. package/plugins/agents/chat/collections/intent.d.ts +7 -7
  47. package/plugins/agents/chat/collections/live.d.ts +1 -1
  48. package/plugins/agents/chat/collections/message.d.ts +59 -13
  49. package/plugins/agents/chat/collections/message.js +31 -3
  50. package/plugins/agents/chat/collections/shown.d.ts +1 -1
  51. package/plugins/agents/chat/collections/thread.d.ts +71 -1
  52. package/plugins/agents/chat/collections/thread.js +57 -0
  53. package/plugins/agents/chat/collections/wait.d.ts +1 -1
  54. package/plugins/agents/chat/contract.d.ts +20 -3
  55. package/plugins/agents/chat/contract.js +17 -1
  56. package/plugins/agents/chat/mod.d.ts +27 -1
  57. package/plugins/agents/chat/mod.js +54 -7
  58. package/plugins/agents/chat/processors/turn.js +86 -24
  59. package/plugins/agents/chat/resources/commands.d.ts +5 -0
  60. package/plugins/agents/chat/resources/commands.js +90 -20
  61. package/plugins/agents/chat/resources/tools.js +29 -5
  62. package/plugins/agents/chat/shared/asks.d.ts +81 -0
  63. package/plugins/agents/chat/shared/asks.js +203 -0
  64. package/plugins/agents/chat/shared/delivery.d.ts +10 -0
  65. package/plugins/agents/chat/shared/delivery.js +137 -25
  66. package/plugins/agents/chat/shared/notes.d.ts +28 -0
  67. package/plugins/agents/chat/shared/notes.js +35 -0
  68. package/plugins/agents/chat/shared/send.d.ts +9 -1
  69. package/plugins/agents/chat/shared/send.js +36 -6
  70. package/plugins/agents/chat/shared/share.d.ts +48 -0
  71. package/plugins/agents/chat/shared/share.js +67 -0
  72. package/plugins/agents/chat/shared/types.d.ts +13 -0
  73. package/plugins/agents/chat/shared/unmark.d.ts +145 -0
  74. package/plugins/agents/chat/shared/unmark.js +237 -0
  75. package/plugins/agents/chat/terminal.d.ts +2 -1
  76. package/plugins/agents/chat/terminal.js +6 -2
  77. package/plugins/agents/chat/views/asked.d.ts +35 -0
  78. package/plugins/agents/chat/views/asked.js +89 -0
  79. package/plugins/agents/chat/views/held.d.ts +10 -0
  80. package/plugins/agents/chat/views/held.js +10 -0
  81. package/plugins/agents/chat/views/message.d.ts +1 -0
  82. package/plugins/agents/chat/views/message.js +8 -4
  83. package/plugins/agents/chat/views/terminal/asks.d.ts +14 -0
  84. package/plugins/agents/chat/views/terminal/asks.js +35 -0
  85. package/plugins/agents/chat/views/terminal/message.js +9 -9
  86. package/plugins/agents/chat/views/terminal/moving.d.ts +11 -0
  87. package/plugins/agents/chat/views/terminal/moving.js +27 -0
  88. package/plugins/agents/chat/views/web/asking.d.ts +11 -0
  89. package/plugins/{compute/computers/views/web/waiting.js → agents/chat/views/web/asking.js} +10 -9
  90. package/plugins/agents/chat/views/web/asks.d.ts +42 -0
  91. package/plugins/agents/chat/views/web/asks.js +170 -0
  92. package/plugins/agents/chat/views/web/composer.d.ts +23 -1
  93. package/plugins/agents/chat/views/web/composer.js +37 -3
  94. package/plugins/agents/chat/views/web/conversation.d.ts +58 -0
  95. package/plugins/agents/chat/views/web/conversation.js +130 -55
  96. package/plugins/agents/chat/views/web/handed.d.ts +6 -0
  97. package/plugins/agents/chat/views/web/handed.js +38 -0
  98. package/plugins/agents/chat/views/web/header.d.ts +10 -6
  99. package/plugins/agents/chat/views/web/header.js +2 -2
  100. package/plugins/agents/chat/views/web/lane.d.ts +11 -0
  101. package/plugins/agents/chat/views/web/lane.js +44 -0
  102. package/plugins/agents/chat/views/web/listed.d.ts +9 -1
  103. package/plugins/agents/chat/views/web/listed.js +14 -2
  104. package/plugins/agents/chat/views/web/message.d.ts +7 -4
  105. package/plugins/agents/chat/views/web/message.js +28 -20
  106. package/plugins/agents/chat/views/web/move.d.ts +7 -2
  107. package/plugins/agents/chat/views/web/move.js +40 -9
  108. package/plugins/agents/chat/views/web/moving.d.ts +21 -0
  109. package/plugins/agents/chat/views/web/moving.js +46 -0
  110. package/plugins/agents/chat/views/web/notes-lane.d.ts +66 -0
  111. package/plugins/agents/chat/views/web/notes-lane.js +57 -0
  112. package/plugins/agents/chat/views/web/notes.d.ts +16 -0
  113. package/plugins/agents/chat/views/web/notes.js +36 -0
  114. package/plugins/agents/chat/views/web/palette.js +2 -2
  115. package/plugins/agents/chat/views/web/plain.d.ts +8 -1
  116. package/plugins/agents/chat/views/web/plain.js +18 -1
  117. package/plugins/agents/chat/views/web/send-on.d.ts +29 -0
  118. package/plugins/agents/chat/views/web/send-on.js +68 -0
  119. package/plugins/agents/chat/views/web/style.d.ts +5 -3
  120. package/plugins/agents/chat/views/web/style.js +158 -5
  121. package/plugins/agents/chat/views/web/words.d.ts +1 -1
  122. package/plugins/agents/chat/views/web/words.js +114 -3
  123. package/plugins/agents/chat/web.d.ts +20 -3
  124. package/plugins/agents/chat/web.js +32 -4
  125. package/plugins/agents/history/collections/summary.d.ts +1 -1
  126. package/plugins/agents/history/processors/compact.js +1 -1
  127. package/plugins/agents/history/resources/tools.js +5 -1
  128. package/plugins/agents/history/shared/lines.d.ts +4 -3
  129. package/plugins/agents/history/shared/lines.js +5 -2
  130. package/plugins/agents/memory/collections/memory.d.ts +1 -1
  131. package/plugins/agents/memory/mod.d.ts +1 -1
  132. package/plugins/agents/memory/mod.js +1 -1
  133. package/plugins/agents/memory/shared/scope.js +1 -1
  134. package/plugins/agents/routines/collections/routine.d.ts +1 -1
  135. package/plugins/agents/routines/collections/run.d.ts +1 -1
  136. package/plugins/agents/routines/resources/tools.js +3 -0
  137. package/plugins/agents/routines/shared/routines.d.ts +1 -1
  138. package/plugins/agents/routines/shared/schedule.d.ts +1 -1
  139. package/plugins/billing/usage/views/web/words.d.ts +1 -1
  140. package/plugins/compute/computers/actions/allow-origin.js +3 -4
  141. package/plugins/compute/computers/actions/forget.js +2 -11
  142. package/plugins/compute/computers/actions/upgrade-asks.d.ts +1 -0
  143. package/plugins/compute/computers/actions/upgrade-asks.js +29 -0
  144. package/plugins/compute/computers/collections/desk.d.ts +1 -1
  145. package/plugins/compute/computers/mod.d.ts +7 -5
  146. package/plugins/compute/computers/mod.js +18 -15
  147. package/plugins/compute/computers/processors/left.js +1 -1
  148. package/plugins/compute/computers/program/version.d.ts +1 -1
  149. package/plugins/compute/computers/program/version.js +1 -1
  150. package/plugins/compute/computers/resources/commands.d.ts +2 -3
  151. package/plugins/compute/computers/resources/commands.js +2 -55
  152. package/plugins/compute/computers/resources/downloads.js +1 -1
  153. package/plugins/compute/computers/shared/ask.d.ts +37 -14
  154. package/plugins/compute/computers/shared/ask.js +57 -105
  155. package/plugins/compute/computers/shared/desks.js +2 -2
  156. package/plugins/compute/computers/shared/upgrade.d.ts +42 -0
  157. package/plugins/compute/computers/shared/upgrade.js +44 -0
  158. package/plugins/compute/computers/terminal.d.ts +4 -3
  159. package/plugins/compute/computers/terminal.js +5 -6
  160. package/plugins/compute/computers/views/web/allowed.d.ts +2 -2
  161. package/plugins/compute/computers/views/web/allowed.js +4 -4
  162. package/plugins/compute/computers/views/web/asked.d.ts +0 -2
  163. package/plugins/compute/computers/views/web/asked.js +0 -18
  164. package/plugins/compute/computers/views/web/asks.d.ts +14 -18
  165. package/plugins/compute/computers/views/web/asks.js +9 -70
  166. package/plugins/compute/computers/views/web/routine-panel.js +12 -5
  167. package/plugins/compute/computers/views/web/style.d.ts +6 -6
  168. package/plugins/compute/computers/views/web/style.js +8 -39
  169. package/plugins/compute/computers/web.d.ts +7 -9
  170. package/plugins/compute/computers/web.js +17 -15
  171. package/plugins/interfaces/maintenance/contract.d.ts +5 -1
  172. package/plugins/interfaces/maintenance/mod.d.ts +3 -0
  173. package/plugins/interfaces/maintenance/mod.js +3 -0
  174. package/plugins/interfaces/maintenance/resources/routes.d.ts +4 -0
  175. package/plugins/interfaces/maintenance/resources/routes.js +19 -0
  176. package/plugins/interfaces/mcp/actions/call.js +2 -23
  177. package/plugins/interfaces/mcp/actions/public.d.ts +8 -0
  178. package/plugins/interfaces/mcp/actions/public.js +81 -0
  179. package/plugins/interfaces/mcp/mod.d.ts +31 -0
  180. package/plugins/interfaces/mcp/mod.js +33 -0
  181. package/plugins/interfaces/mcp/resources/limits.d.ts +38 -0
  182. package/plugins/interfaces/mcp/resources/limits.js +77 -0
  183. package/plugins/interfaces/mcp/resources/public.d.ts +45 -0
  184. package/plugins/interfaces/mcp/resources/public.js +99 -0
  185. package/plugins/interfaces/mcp/resources/server.d.ts +5 -1
  186. package/plugins/interfaces/mcp/resources/server.js +21 -4
  187. package/plugins/interfaces/mcp/resources/tools.js +6 -3
  188. package/plugins/interfaces/mcp/shared/settings.d.ts +37 -6
  189. package/plugins/interfaces/mcp/shared/settings.js +48 -7
  190. package/plugins/interfaces/mcp/shared/shown.d.ts +20 -0
  191. package/plugins/interfaces/mcp/shared/shown.js +31 -0
  192. package/plugins/interfaces/voice/collections/call.d.ts +1 -1
  193. package/plugins/interfaces/web/collections/visitor.d.ts +1 -1
  194. package/plugins/interfaces/whatsapp/collections/phone.d.ts +1 -1
  195. package/plugins/models/actions/check.js +5 -3
  196. package/plugins/models/actions/offered.js +6 -2
  197. package/plugins/models/actions/price.d.ts +0 -2
  198. package/plugins/models/actions/price.js +5 -5
  199. package/plugins/models/shared/choice.d.ts +8 -0
  200. package/plugins/models/shared/choice.js +37 -3
  201. package/plugins/models/shared/embed.js +2 -1
  202. package/plugins/models/shared/generate.js +2 -1
  203. package/plugins/models/shared/image.js +2 -1
  204. package/plugins/models/shared/transcribe.js +2 -1
  205. package/runtime/api.js +1 -1
  206. package/runtime/define.d.ts +7 -4
  207. package/runtime/describe.d.ts +2 -0
  208. package/runtime/describe.js +5 -2
  209. package/runtime/errors.d.ts +7 -0
  210. package/runtime/errors.js +7 -0
  211. package/runtime/executor.js +18 -9
  212. package/runtime/mod.d.ts +1 -1
  213. package/runtime/mod.js +1 -1
  214. package/runtime/owner.js +48 -4
  215. package/runtime/schedules.d.ts +23 -4
  216. package/runtime/schedules.js +9 -2
  217. package/runtime/timers.d.ts +4 -1
  218. package/runtime/timers.js +34 -10
  219. package/runtime/wire.d.ts +9 -1
  220. package/runtime/wire.js +10 -1
  221. package/stores/sql/sqlite/mod.d.ts +8 -1
  222. package/stores/sql/sqlite/mod.js +14 -2
  223. package/plugins/access/spaces/actions/share.d.ts +0 -1
  224. package/plugins/access/spaces/actions/share.js +0 -36
  225. package/plugins/compute/computers/actions/approve.js +0 -95
  226. package/plugins/compute/computers/collections/approval.js +0 -79
  227. package/plugins/compute/computers/shared/asks.d.ts +0 -5
  228. package/plugins/compute/computers/shared/asks.js +0 -4
  229. package/plugins/compute/computers/shared/grants.d.ts +0 -32
  230. package/plugins/compute/computers/shared/grants.js +0 -66
  231. package/plugins/compute/computers/views/terminal/approvals.d.ts +0 -9
  232. package/plugins/compute/computers/views/terminal/approvals.js +0 -16
  233. package/plugins/compute/computers/views/web/waiting.d.ts +0 -10
  234. /package/plugins/{compute/computers → agents/chat}/actions/approve.d.ts +0 -0
  235. /package/plugins/{compute/computers → agents/chat}/actions/forget-grant.d.ts +0 -0
package/AGENTS.md ADDED
@@ -0,0 +1,399 @@
1
+ # AGENTS.md
2
+
3
+ A guide for coding agents (Claude Code, Codex, Cursor, Gemini) building an app with Copilotz. Read
4
+ it whole before you write code. The last section is for work on Copilotz itself.
5
+
6
+ It ships in the package (`node_modules/copilotz/AGENTS.md`, and `@copilotz/copilotz` on JSR) and
7
+ goes with `copilotz@1.0.0-rc.47`. Every docs page is Markdown at
8
+ `https://copilotz.com/docs/<slug>.md`, and https://copilotz.com/llms.txt lists them all. When you're
9
+ unsure of a name, fetch its page or read the package's types (`node_modules/copilotz/**/*.d.ts`).
10
+ Don't guess.
11
+
12
+ It also comes as an Agent Skill, for any coding agent: `npx skills add copilotzhq/copilotz`.
13
+
14
+ ## What Copilotz is
15
+
16
+ A runtime for apps that people and AI use alike. You write the app once: its data, what can be done,
17
+ who may do it, and how it shows. People use it on a web page or in a terminal, the app's own agents
18
+ through tools, and outside assistants (ChatGPT, Claude, any MCP client) over MCP. Every way in calls
19
+ the same Actions, under the same rules, and every write is on one record of who did what, for whom.
20
+ It runs on Node 24+, Deno 2.9+ and Bun.
21
+
22
+ ## How Copilotz works, in one minute
23
+
24
+ An app is a **runtime** made of **plugins**. A plugin is plain objects, made of six primitives:
25
+
26
+ | Primitive | What it is |
27
+ | -------------- | ---------------------------------------------------------------------------------------- |
28
+ | **Collection** | documents with a JSON Schema, read and written with the MongoDB collection API |
29
+ | **Action** | something that can be done, by name, with a JSON Schema `input` and an `allow` (who may) |
30
+ | **Processor** | what happens when events happen: it hears the events it names, at least once, in order |
31
+ | **View** | how data shows in one place: text for a model or the terminal, Ink, React for the web |
32
+ | **Resource** | configuration as named plain objects, by kind (`agents`, `tools`, `provider`…) |
33
+ | **Adapter** | one implementation of a port, by name: a model provider's protocol, an email service |
34
+
35
+ A plugin may also declare `routes` and `who` (HTTP), `guard` (rules), `schedules` and a startup
36
+ `check`. Plugins merge in order: a later plugin's resources patch an earlier one's (objects merge,
37
+ `null` removes), and a later View, adapter or route replaces one of the same name.
38
+
39
+ The runtime keeps one contract for every caller:
40
+
41
+ - **Who, for whom, where.** Every call carries an actor, `{ kind, id, for?, in? }`: a person, a
42
+ contact from outside, or an agent working `for` one of them. `in` is where the work is (a space,
43
+ with the access plugin).
44
+ - **The rules, at the data.** Reads come back filtered by what the actor reaches, and writes are
45
+ checked, whichever way the call came in.
46
+ - **The record.** Every write records an event in the same commit, naming its actor.
47
+
48
+ What people often get wrong:
49
+
50
+ - **Two kinds of events.** A collection write records `<collection>.created`, `.updated` or
51
+ `.deleted`. An Action call records `action.started`, then `action.completed` or `action.failed`.
52
+ Callers call Actions; events are what Actions and writes produce.
53
+ - **`runtime.subscribe` hears events; `runtime.observe` keeps a View live**, running it again when a
54
+ commit changes what it read.
55
+ - **Queries read; Actions write.** Named queries and Views never write.
56
+
57
+ Plugins reach each other only through the runtime, by name. One that builds on another says so
58
+ (`requires: ["chat"]`) and imports only that plugin's `contract.ts`, never its code.
59
+
60
+ ## Start a project
61
+
62
+ There's no project generator. Set a project up as the docs' courses do, on Node 24 or newer:
63
+
64
+ ```sh
65
+ mkdir my-app && cd my-app
66
+ npm init -y && npm pkg set type=module
67
+ npm install copilotz@1.0.0-rc.47 react@19 react-dom@19
68
+ npm install -D typescript @types/node @types/react @types/react-dom esbuild
69
+ ```
70
+
71
+ Pin the version: npm's `latest` tag still points at an early release candidate. On Deno, run
72
+ `deno add jsr:@copilotz/copilotz` and map `"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.47"` in
73
+ `deno.json`, so imports read the same.
74
+
75
+ Node runs `.ts` files as they are, so there's no build step. It doesn't run `.tsx`: tests that load
76
+ a `web.tsx` need a loader hook (Getting Started chapter 3 adds one). Copy `tsconfig.json` from
77
+ [Build Compass](https://copilotz.com/docs/build-compass.md), under "What you need": `NodeNext`
78
+ modules, `allowImportingTsExtensions`, `verbatimModuleSyntax`, `erasableSyntaxOnly`, `strict`,
79
+ `noEmit`, and `jsx: "react-jsx"`. The scripts, in `package.json` (add `dev` and `terminal` once
80
+ there's a server and a terminal):
81
+
82
+ ```json
83
+ "scripts": {
84
+ "test": "node --disable-warning=ExperimentalWarning --test --test-timeout=60000 --test-concurrency=1 \"tests/*.test.ts\"",
85
+ "check": "tsc --noEmit -p ."
86
+ }
87
+ ```
88
+
89
+ The layout the docs use:
90
+
91
+ ```text
92
+ app.ts plugins(settings): every plugin, in order. It reads no environment.
93
+ plugins/<name>/
94
+ mod.ts assembles the plugin, and nothing else
95
+ actions.ts … one file per primitive; or collections/, actions/, views/… with one file per
96
+ declaration, as Copilotz's own plugins are laid out
97
+ contract.ts what other plugins may import: shapes and small helpers, never code
98
+ web.tsx its web front end (React Views); terminal.ts, its terminal one
99
+ server.ts the web host: reads the environment, passes settings to plugins()
100
+ tests/kit.ts the app as app.ts makes it, in memory, with a scripted model
101
+ tests/*.test.ts
102
+ .env OPENAI_API_KEY=… (optional; dev and terminal read it: --env-file-if-exists=.env)
103
+ ```
104
+
105
+ **Give the project its own guide.** Write `AGENTS.md` at its root, and `CLAUDE.md` holding the one
106
+ line `@AGENTS.md` (Claude Code reads `CLAUDE.md`, and follows the import). Keep it short and true:
107
+
108
+ ```markdown
109
+ # AGENTS.md
110
+
111
+ This app runs on Copilotz (copilotz@1.0.0-rc.47). Read node_modules/copilotz/AGENTS.md first;
112
+ https://copilotz.com/llms.txt lists the docs, as Markdown.
113
+
114
+ - `npm test` runs every test offline, with a scripted model: run it after each change.
115
+ `npm run check` checks the types.
116
+ - `app.ts` lists the plugins in order; `plugins/<name>/mod.ts` assembles each one.
117
+ - Every change to data is an Action that pages, tools and scripts all call. Access rules live at the
118
+ data (the `shared` resource or a `guard`). Each tool has a `tool:<name>` View.
119
+ ```
120
+
121
+ ## A plugin, end to end
122
+
123
+ A collection, an Action, a View for people and one for the model, a rule, a tool and an agent, in
124
+ `plugins/tasks/mod.ts`:
125
+
126
+ ```ts
127
+ import { defineAction, definePlugin, failure, people } from "copilotz";
128
+ import type { Plugin, ViewContext } from "copilotz";
129
+ import { tool } from "copilotz/plugins/agents";
130
+
131
+ type Task = { _id: string; title: string; in: string };
132
+
133
+ export const tasks: Plugin = definePlugin({
134
+ name: "tasks",
135
+ requires: ["chat", "spaces"],
136
+ collections: {
137
+ task: {
138
+ schema: {
139
+ type: "object",
140
+ properties: { title: { type: "string" }, in: { type: "string" } },
141
+ required: ["title", "in"],
142
+ },
143
+ },
144
+ },
145
+ actions: {
146
+ // The one way to add a task: a button, the agent's tool and a script all call it.
147
+ "task.add": defineAction({
148
+ input: { type: "object", properties: { title: { type: "string" } }, required: ["title"] },
149
+ allow: people,
150
+ run: async (ctx, { title }) => {
151
+ if (!ctx.in) throw failure("invalid", "Add tasks in a space.", { public: true });
152
+ const { insertedId } = await ctx.db.collection("task").insertOne({ title, in: ctx.in });
153
+ return { task: insertedId };
154
+ },
155
+ }),
156
+ },
157
+ views: {
158
+ // Text, for the terminal and for a model. It reads as whoever looks.
159
+ tasks: (_: unknown, ctx: ViewContext) => {
160
+ const found = ctx.db.collection<Task>("task").find({}).value ?? [];
161
+ return found.length ? found.map((t) => `- ${t.title}`).join("\n") : "No tasks.";
162
+ },
163
+ // What a model reads after it calls add_task.
164
+ "tool:add_task": (_call: unknown, ctx: ViewContext) => ctx.show("tasks", {}),
165
+ },
166
+ resources: {
167
+ // The rule, at the data: a task lives in a space (its `in`).
168
+ shared: { task: {} },
169
+ tools: {
170
+ add_task: tool({
171
+ description: "Adds a task to this chat's space",
172
+ input: { type: "object", properties: { title: { type: "string" } }, required: ["title"] },
173
+ run: ({ title }, ctx) => ctx.call("task.add", { title }),
174
+ }),
175
+ },
176
+ agents: {
177
+ helper: { default: true, instructions: "Keep tasks.", model: "helper", tools: ["add_task"] },
178
+ },
179
+ },
180
+ });
181
+ ```
182
+
183
+ `app.ts` lists the plugins and sets the model alias the agent names. Without a key it's
184
+ `"fake/echo"`, Copilotz's offline model: it echoes what it's told, and calls a tool, with no input,
185
+ when the message names it ("add task" for `add_task`).
186
+
187
+ ```ts
188
+ import { definePlugin, type Plugin } from "copilotz";
189
+ import { models } from "copilotz/plugins/models";
190
+ import { chat } from "copilotz/plugins/agents";
191
+ import { access } from "copilotz/plugins/access";
192
+ import { tasks } from "./plugins/tasks/mod.ts";
193
+
194
+ export function plugins(settings: { openai?: string } = {}): Plugin[] {
195
+ const provider = settings.openai ? { openai: { apiKey: settings.openai } } : {};
196
+ const model = { helper: settings.openai ? "openai/gpt-5.4-mini" : "fake/echo" };
197
+ const app = definePlugin({ name: "app-settings", resources: { provider, model } });
198
+ return [models, chat, ...access, tasks, app];
199
+ }
200
+ ```
201
+
202
+ ## Test without an API key: the default loop
203
+
204
+ Run `npm test` after every change, and `npm run check` before you stop. No test needs a key or the
205
+ network. Run the app as `app.ts` makes it, with fakes only where it meets the world: a scripted
206
+ model (below); `createRuntime({ clock: manualClock(Date.now()) })` and `clock.advance(ms)` for time;
207
+ `createRuntime({ fetch })` for what plugins call outside (`ctx.fetch`). A model provider is called
208
+ with the platform's `fetch`, so a fake one is a local server (`serve`, from `copilotz/testing`) set
209
+ as the provider's `baseURL`. `runtime.fetch(new Request(…))` tests HTTP without a port, and
210
+ `await runtime.idle()` waits until nothing is left to run.
211
+
212
+ `tests/kit.ts`:
213
+
214
+ ```ts
215
+ import { createRuntime, definePlugin } from "copilotz";
216
+ import { memoryStore } from "copilotz/stores/memory";
217
+ import type { LlmAdapter, LlmRequest } from "copilotz/plugins/models";
218
+ import { plugins } from "../app.ts";
219
+
220
+ export type Move = string | { tool: string; input?: Record<string, unknown> };
221
+
222
+ /** A model that plays its moves in order, one per call, and keeps what each call sent it. */
223
+ export function scripted(moves: Move[]) {
224
+ const sent: LlmRequest[] = [];
225
+ const adapter: LlmAdapter = {
226
+ async *generate(request) {
227
+ sent.push(request);
228
+ const move = moves.shift();
229
+ if (move === undefined) throw new Error(`The script has no move for call ${sent.length}.`);
230
+ if (typeof move === "string") yield { type: "text", text: move };
231
+ else {
232
+ const call = { id: `call-${sent.length}`, name: move.tool, input: move.input ?? {} };
233
+ yield { type: "tool_call", call };
234
+ }
235
+ },
236
+ };
237
+ return { adapter, sent };
238
+ }
239
+
240
+ /** The app, in memory, with the `helper` alias on a script. */
241
+ export async function start(moves: Move[] = []) {
242
+ const store = memoryStore();
243
+ const helper = scripted(moves);
244
+ const script = definePlugin({
245
+ name: "test-script",
246
+ resources: { provider: { script: { adapter: "script" } }, model: { helper: "script/helper" } },
247
+ adapters: { llm: { script: helper.adapter } },
248
+ });
249
+ const runtime = await createRuntime({ store, plugins: [...plugins(), script] });
250
+ return { runtime, store, helper };
251
+ }
252
+ ```
253
+
254
+ `tests/tasks.test.ts`:
255
+
256
+ ```ts
257
+ import assert from "node:assert/strict";
258
+ import { test } from "node:test";
259
+ import { type Actor, personOf } from "copilotz";
260
+ import { start } from "./kit.ts";
261
+
262
+ test("the agent adds a task for Ana, through the same Action", async () => {
263
+ const { runtime, store, helper } = await start([
264
+ { tool: "add_task", input: { title: "Bo" } },
265
+ "Done.",
266
+ ]);
267
+ try {
268
+ const ana: Actor = { kind: "person", id: "ana" };
269
+ const { space } = await runtime.call<{ space: string }>("space.personal", {}, { actor: ana });
270
+ const here: Actor = { ...ana, in: space };
271
+ await runtime.call("chat.send", { in: space, text: "Add Bo." }, { actor: here });
272
+ await runtime.idle();
273
+ assert.equal(helper.sent[1].messages.at(-1)?.text, "- Bo"); // what the model read
274
+ const made = (await store.events(0)).find((e) => e.type === "task.created");
275
+ assert.equal(personOf(made?.actor), "ana"); // the record: written for Ana…
276
+ assert.equal(made?.actor?.kind, "agent"); // …by the agent
277
+ const seen = await runtime.observe<string>("tasks", {}, { actor: here }).ready;
278
+ assert.deepEqual(seen, { status: "ready", value: "- Bo" }); // what Ana sees
279
+ } finally {
280
+ await runtime.close();
281
+ }
282
+ });
283
+ ```
284
+
285
+ Test what callers may not do as well: call as someone else, and `assert.rejects`.
286
+
287
+ ## Rules: do this, not that
288
+
289
+ - **One Action per change, called from every way in.** A button and a tool call it with `ctx.call`,
290
+ a script with `runtime.call`. Never add a second, looser path. A tool is a thin caller of Actions.
291
+ - **Rules at the data, not in handlers.** Name a collection in the `shared` resource (its documents
292
+ live `in` a space; `part` ties one to another document, as a booking to its chat), or write a
293
+ `guard`. Don't filter by who's asking inside an Action. To keep a collection changing only through
294
+ its Actions, refuse `direct` writes in a `guard`.
295
+ - **Say `allow` on every Action outsiders call:** `people`, `contacts`, `peopleOrContacts`,
296
+ `publicCallers`, or `inPerson` for what only the person decides (consent, keys, who's in a space,
297
+ money). Write it by kind, never by identity. It's asked of agents too, and of whom they work for.
298
+ An Action without `allow` is internal.
299
+ - **A View for whatever anyone reads, a model included.** Each tool gets a `tool:<name>` View: short
300
+ text, with ids the model can act on. A failed call's output is its error's words; pass them on,
301
+ don't throw. An MCP server that offers a tool without its View doesn't start.
302
+ - **A View reads in its own body.** A React View reads with `ctx.db` and hands the result to its
303
+ component, so it stays live. Views never write.
304
+ - **Errors for callers are `failure(code, message, { public: true })`.** Only a public failure's
305
+ words reach a caller outside or a model.
306
+ - **Settings are resources, not code.** `app.ts` reads no environment: the server, the terminal or a
307
+ test passes settings in. Agents name a model alias that the app sets.
308
+ - **Writes that must agree go in one `ctx.transaction`.** A refused write rolls it all back. It
309
+ holds the store's writer, so keep slow work out.
310
+ - **Who acts:** `personOf(ctx.actor)`, not `ctx.actor.id` (an agent's is its own). Where: `ctx.in`.
311
+ A tool works where its chat is.
312
+ - **Going past the actor's reach is a named grant,** `ctx.as(grant("…"))`, in trusted code, on the
313
+ record. Keys stay in code: never in Action inputs (they're recorded), never with a model.
314
+ - **An agent tells a conversation only what everyone in it could see.** Its work reads what both its
315
+ asker and the place its answer goes reach: a space and what it draws on; a customer's chat, what
316
+ that customer reaches (a space drawing on another with `contacts: "read"` lets them read it); its
317
+ person's Personal space, all they reach. Writing anywhere its readers don't all reach that asks
318
+ the person first (`needs_approval`): don't catch it, let it through to the turn.
319
+ - **A tool that goes past its caller, offered to a contact or the public, is a declassifier.** Scope
320
+ it to them (their own bookings, never any record), take no free-form query that could widen it,
321
+ and return only what they may see. In a customer's chat, an Action people call that goes past its
322
+ caller is refused; the app's own (no `allow`) runs as its tool chose. The public (`publicCallers`,
323
+ `{ kind: "public" }`) reads only spaces that have it as a viewer, and writes nothing.
324
+ - **Outside effects:** write the intent, call out with its id as the idempotency key (a tool's
325
+ `callId`), then write the result.
326
+ - **Online:** `devSignIn` is for this machine only; Copilotz won't start it with a public origin.
327
+ Keep the `links` secret (32 bytes or more) across restarts, or MCP conversations start over.
328
+
329
+ ## Recipes
330
+
331
+ Each link is a page as Markdown. GS is Getting Started (a salon's bookings, 10 chapters). BC is
332
+ Build Compass (41 chapters, written for an earlier release candidate: check names in the reference).
333
+
334
+ - A plugin: [GS 1](https://copilotz.com/docs/getting-started/01-one-booking.md). People, contacts,
335
+ spaces, the rules: [GS 2](https://copilotz.com/docs/getting-started/02-who-sees-what.md).
336
+ - The web: [GS 3](https://copilotz.com/docs/getting-started/03-its-own-web-page.md),
337
+ [serving on the web](https://copilotz.com/docs/guides/serving-on-the-web.md). An agent and its
338
+ tools: [GS 4](https://copilotz.com/docs/getting-started/04-its-own-agent.md).
339
+ - MCP: [GS 5](https://copilotz.com/docs/getting-started/05-chatgpt-claude-and-gemini-over-mcp.md).
340
+ One test, every way in:
341
+ [GS 6](https://copilotz.com/docs/getting-started/06-the-same-bookings-every-way-in.md).
342
+ - Widgets: [GS 7](https://copilotz.com/docs/getting-started/07-a-widget-in-the-assistant.md). A
343
+ site's chat: [GS 8](https://copilotz.com/docs/getting-started/08-a-chat-on-your-site.md).
344
+ WhatsApp: [GS 9](https://copilotz.com/docs/getting-started/09-whatsapp.md).
345
+ - Shipping (SQLite, PostgreSQL, sign-in by email):
346
+ [GS 10](https://copilotz.com/docs/getting-started/10-shipping-the-salon.md). A container of 512
347
+ MiB or less (Deno 2.9+, `--max-semi-space-size=2`, SQLite's cache, each plugin from its own entry
348
+ point): [memory](https://copilotz.com/docs/operations/memory.md).
349
+ - The prompt and context Views:
350
+ [BC 2](https://copilotz.com/docs/build-compass/part-1-an-agent-of-your-own/02-north-in-your-terminal.md),
351
+ [BC 4](https://copilotz.com/docs/build-compass/part-2-your-own-plugins/04-today-every-turn.md).
352
+ - A Processor:
353
+ [BC 6](https://copilotz.com/docs/build-compass/part-2-your-own-plugins/06-chats-that-name-themselves.md).
354
+ Transactions:
355
+ [BC 9](https://copilotz.com/docs/build-compass/part-3-the-board/09-the-boards-data-and-actions.md).
356
+ - Schedules and a manual clock:
357
+ [BC 27](https://copilotz.com/docs/build-compass/part-8-skills-and-routines/27-routines-on-a-schedule.md).
358
+ Fakes at the edges:
359
+ [BC 31](https://copilotz.com/docs/build-compass/part-10-testing/31-fakes-at-the-edges.md).
360
+ - Scripts over REST: [REST and the client](https://copilotz.com/docs/guides/rest-and-the-client.md).
361
+ Many orgs: [many orgs](https://copilotz.com/docs/guides/many-orgs.md).
362
+ - Every entry point, option, event and context field:
363
+ [reference](https://copilotz.com/docs/reference.md). Each of Copilotz's plugins (`chat`, `spaces`,
364
+ `mcp`…): [plugins](https://copilotz.com/docs/reference/plugins.md). How it runs:
365
+ [architecture](https://copilotz.com/docs/architecture.md).
366
+
367
+ ## Entry points
368
+
369
+ The same names on npm (`copilotz/…`) and JSR (`@copilotz/copilotz/…`); the package's `package.json`
370
+ lists them all. Besides those above: `copilotz/stores/sqlite` and `copilotz/stores/postgres`
371
+ (stores), `copilotz/plugins/interfaces` (`mcp`, `api`, `whatsapp`, `voice`, `webLines`),
372
+ `copilotz/web` (the web host, `web`), `copilotz/web/server` (`webPage`), `copilotz/web/node`
373
+ (`listen`, `serve`, `bundle`), `copilotz/terminal` (`terminal`) and `copilotz/testing`. Each plugin
374
+ of `agents`, `access` and `interfaces` is also its own entry point, which loads it alone:
375
+ `copilotz/plugins/interfaces/mcp`, `copilotz/plugins/agents/chat`, `copilotz/plugins/access/spaces`…
376
+ Front ends sit beside each theme (`copilotz/plugins/agents/web` has `chatWeb`). Product packages
377
+ ship at the same version: `@copilotz/work` (`boards`, `documents`), `@copilotz/team`,
378
+ `@copilotz/directory` and `@copilotz/billing`.
379
+
380
+ ## Working on Copilotz itself
381
+
382
+ [CONTRIBUTING.md](CONTRIBUTING.md) has the rest. The checks:
383
+
384
+ ```sh
385
+ deno task check && deno task test # types, the suite (COPILOTZ_TEST_POSTGRES_URL: PostgreSQL)
386
+ npm install && npm test # the suite on Node 24 (bun test --timeout 60000 on Bun)
387
+ deno fmt --check # the format CI checks
388
+ npm run build && node scripts/npm/smoke.ts && deno publish --dry-run # the packages
389
+ ```
390
+
391
+ - The runtime imports nothing outside it. A plugin imports the runtime, the hosts' toolkits, its own
392
+ files and other plugins' `contract.ts` (`testing/boundaries.test.ts`).
393
+ - A plugin is `plugins/<theme>/<name>/`, by primitive, one file per declaration; `mod.ts` only
394
+ assembles it. Tests sit in `plugins/<theme>/tests/`. Factories and plain data, no classes.
395
+ - After changing a plugin, `deno run -A scripts/describe.ts --docs` remakes its reference page.
396
+ After changing docs, `python3 scripts/docs-index.py && deno fmt docs`.
397
+ - `testing/agents-md.test.ts` checks this file's imports, links and version;
398
+ `node scripts/version.ts <version>` moves its version with the rest. Releases are tags the
399
+ maintainers push: don't tag or publish.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,111 @@
1
+ ## 1.0.0-rc.47 — 2026-11-13
2
+
3
+ (rc.46 was tagged but never published: a file wasn't formatted, and a test read Windows line endings
4
+ as part of the text. This is it.)
5
+
6
+ **Breaking: what an agent may say is bounded by who will see it.** The old labels (marks on answers,
7
+ hidden until shared) are gone, along with the `share` Action, `needs_share`, message `sources`, the
8
+ "Uses … Not everyone here can see it." notice and `/share`. In their place:
9
+
10
+ - **The bound.** An agent's work reads only what both its asker and its destination reach: a space
11
+ and what it draws on; a customer's chat, what that customer reaches; its person's own Personal
12
+ space, all they reach. Its answer there shows nobody what they couldn't see, so nothing is ever
13
+ hidden once written. The turn's agent carries its conversation (`thread`), and so does a tool
14
+ acting as its agent's person.
15
+ - **Going wider asks first.** Writing anywhere whose readers don't all reach that bound (a Personal
16
+ space's agent posting in Launch, a team's agent writing into a customer's chat, handing work to
17
+ another space) is refused with `needs_approval` (`to`, `named`), and the turn asks its person:
18
+ "May I post this to Launch? Its 12 members will see it.", yes this once, for this conversation,
19
+ for the routine that set it going, or no; never always. On a yes it runs again. Don't catch
20
+ `needs_approval` in a tool: let it through.
21
+ - **One ask for every plugin, in chat** (`approval`, `grant`, `chat.approve`, `chat.forgetGrant`):
22
+ each ask says which answers it takes. Computers use it (`computer.approve` and
23
+ `computer.forgetGrant` are gone); their stored asks and yeses move over on the first start
24
+ (`computer.upgradeAsks`).
25
+ - **Answers handed back** from another space ask "Post here" / "Send it to me only" where that
26
+ space's people don't all reach what the work drew on; from a Personal space they never ask. Work
27
+ handed over from inside a customer's chat is refused: staff use its notes.
28
+ - **In front of a customer,** trusted code going beyond its caller runs only in an Action a contact
29
+ may call, or the app's own (no `allow`), recorded or not. A tool that goes past its caller,
30
+ offered to a contact or the public, is a declassifier: scope it to them (AGENTS.md).
31
+ - **A space drawing on another may let its contacts read it:** `member.set` with `contacts: "read"`
32
+ (read only, one level), for a catalog or policies a line's customers may see.
33
+ - **Staff notes** beside a customer's chat (`<chat>:notes`, `chat.notes`): the team works with its
34
+ agents there, with the space's reach; the customer never sees it; a reply goes over as the
35
+ person's own message.
36
+ - **Moving a conversation names what it shows:** "Everyone in Launch (12) will see this whole
37
+ conversation. It drew on Squad 1 and Finance." (`thread.moving`), from what its agents' messages
38
+ record they drew on (`drew`: a record, never a gate, and only spaces their readers reach).
39
+ - **The public:** `{ kind: "public" }` (`publicCallers`) reads only the spaces that have it as a
40
+ viewer, and writes nothing; a call with no actor is still no one.
41
+ - **Migration, by itself on the first start:** `chat.unmark` moves what the old marks kept hidden:
42
+ in a Personal space they become `drew`; in a customer's chat, the message moves to its staff
43
+ notes; elsewhere, to the Personal space of whom it answered, leaving a placeholder. One log line
44
+ of counts. `deno task unmark --dry-run` rehearses it against a database, writing nothing. Until it
45
+ has run, a contact reads nothing that still carries the old marks.
46
+ - **What code writes is kept as what happened, and said in the reader's words.** A line where a
47
+ reply went (the migration's placeholders; an answer handed back that went to its asker alone, or
48
+ stayed) is a message's `held` (`{ for: <person> }`, or `{}`), with no text. Staff notes and what
49
+ was held from a chat keep that chat's title as it is, `about` and `held: { from }` saying what
50
+ they are. A share's or a hand-back's ask keeps where and to how many, not a sentence. Views say
51
+ them in chat's words (`chat.heldMoved`, `chat.notesOf`, `chat.heldFrom`, `chat.askPost`…), English
52
+ by default, names as they are when read; the asks' cards, the sidebar's waiting list and the
53
+ terminal's notice take every word from there. Agents are told them in English.
54
+ - **Runtime:** a declared schedule may run `once` (on the first start with it); a failure's `detail`
55
+ reaches its caller; operators call `isMaintenance` Actions at
56
+ `POST /maintenance/actions/<action>`.
57
+ - **Less memory for the same app.** The docs app's shape (an MCP server with 3 tools, on the memory
58
+ store), started, after a full GC: Deno 2.9 106 → 90 MiB RSS and Node 24 134 → 103 MiB, with 7 MiB
59
+ less heap, when it imports each plugin from its own entry point.
60
+ [Memory](docs/operations/memory.md), a new page, says how to run an app in a container of 512 MiB
61
+ or less, with what each setting saves:
62
+ - **The model catalog loads the first time a model is resolved,** not with the models plugin. An
63
+ app that never calls a model saves about 5 MiB of heap; one that does sees no change.
64
+ - **SQLite keeps a 2 MiB page cache per connection and maps nothing into memory,** where it kept
65
+ 64 MiB and mapped up to 256 MiB: 15 to 40 MiB less at its peak over 1,000 calls.
66
+ `cacheKiB: 65_536, mmapMiB: 256` gives the old sizes back.
67
+ - **Copilotz needs Deno 2.9 or later.** On an older Deno, the SQLite store says so when it opens,
68
+ instead of failing at its first read ("column index out of range").
69
+ - **The read cache's size** is `createRuntime({ cache: { documents, queries } })` (10,000 and
70
+ 1,000 by default); 1,000 and 100 kept 3.5 MiB less heap over 1,000 calls.
71
+ - **V8's young generation, capped** (`--max-semi-space-size=2` on Node,
72
+ `--v8-flags=--max-semi-space-size=2` on Deno), took 55 to 110 MiB off the peak over 1,000 calls.
73
+ - The suite holds the docs app's shape to a memory budget on Deno and Node
74
+ (`bench/memory/budget.test.ts`).
75
+ - **A public MCP server keeps nothing** (`public: true` on `resources.mcp.<name>`, for a docs
76
+ site's): each call runs its tool as the public, with no contact, chat, step, receipt or event. It
77
+ lists only the tools that only read (`annotations.readOnly`), with no `chat` handle, and reads
78
+ what the spaces that have the public as a viewer hold. Calls are limited at once, a minute by
79
+ address (as the `caller` front says it, else the socket) and on the whole server (`ipPerMinute`,
80
+ `linePerMinute`), in memory of a fixed size, and stopped past `timeout`. The docs app's shape,
81
+ 1,000 calls without a handle: from 5 documents and 17 events a call to none, from 31.7 KB of heap
82
+ kept a call to 1.5, and a peak of 261 MiB to 119, on Node 24 (on Deno 2.9: 25.7 KB to 1.0, 195 MiB
83
+ to 113). A tool offered there that goes past the public's reach is a declassifier (see the `mcp`
84
+ reference).
85
+ - **New entry points, one per plugin:** `copilotz/plugins/agents/<name>` (`chat`, `history`,
86
+ `memory`, `skills`, `routines`, `openapi`, `webtools`), `copilotz/plugins/access/<name>`
87
+ (`spaces`, `identity`, `contacts`, `google`, `email`, `dev`, `accounts`) and
88
+ `copilotz/plugins/interfaces/<name>` (`mcp`, `api`, `whatsapp`, `voice`), on npm and JSR. Each
89
+ loads its plugin alone; the themes' entry points stay as they were.
90
+
91
+ **The Copilotz agent plugin.** Coding agents can install a `copilotz` skill (`skills/copilotz/`:
92
+ setup, the offline test loop with the scripted model, the rules, the audience rule included) with
93
+ `npx skills add copilotzhq/copilotz`, or as a plugin: Claude Code (`.claude-plugin/`), Agent Plugins
94
+ (`plugin.json`, read by Codex, Cursor and Copilot CLI) and Gemini CLI (`gemini-extension.json`). The
95
+ docs over MCP come in a later change, once they're live: no manifest wires a server before then.
96
+ `testing/skill.test.ts` checks the skill's imports, docs slugs, links and commands, and that the
97
+ manifests agree; the release script now sets their versions too.
98
+
99
+ ## 1.0.0-rc.45 — 2026-11-12
100
+
101
+ - **AGENTS.md, a guide for coding agents.** Claude Code, Codex, Cursor or Gemini building an app
102
+ with Copilotz finds it in the package (`node_modules/copilotz/AGENTS.md`, and in
103
+ `@copilotz/copilotz` on JSR): how Copilotz works, how to set up a project and test it offline with
104
+ a scripted model, the rules the docs insist on, and links to the docs' pages as Markdown. It has
105
+ each project keep an `AGENTS.md` of its own, with a `CLAUDE.md` that imports it.
106
+ `testing/agents-md.test.ts` checks that what it imports, links and installs is there, and the npm
107
+ smoke test that the installed package has it.
108
+
1
109
  ## 1.0.0-rc.44 — 2026-11-12
2
110
 
3
111
  (rc.43 was tagged but never published: a file wasn't formatted. This is it.)
package/README.md CHANGED
@@ -150,11 +150,15 @@ ana sees: Tue 10:00, Wed 15:00
150
150
  ## Install and run
151
151
 
152
152
  ```sh
153
- npm install copilotz # Node 24+ (npm, pnpm, yarn)
154
- bun add copilotz # Bun
155
- deno add jsr:@copilotz/copilotz # Deno (or `deno add npm:copilotz`)
153
+ npm install copilotz@next # Node 24+ (npm, pnpm, yarn)
154
+ bun add copilotz@next # Bun
155
+ deno add jsr:@copilotz/copilotz@^1.0.0-rc.47 # Deno 2.9+ (or `deno add npm:copilotz@next`)
156
156
  ```
157
157
 
158
+ Until 1.0, the release candidates are on npm's `next` tag, and a plain `npm install copilotz` or
159
+ `deno add jsr:@copilotz/copilotz` gets an older version. At 1.0, stable installs drop `@next` and
160
+ the version.
161
+
158
162
  Save the example as `salon.ts`, and run it with an OpenAI key:
159
163
 
160
164
  ```sh
@@ -162,9 +166,9 @@ OPENAI_API_KEY=sk-… node salon.ts # or bun salon.ts, or deno run -A salon.t
162
166
  ```
163
167
 
164
168
  On Deno, map the name `copilotz` in `deno.json`
165
- (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.44"`) so the imports read the same everywhere.
166
- Copilotz runs on Node, Deno and Bun, and it's built on web standards for Cloudflare Workers and the
167
- browser.
169
+ (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.47"`) so the imports read the same everywhere.
170
+ Copilotz runs on Node 24+, Deno 2.9+ and Bun, and it's built on web standards for Cloudflare Workers
171
+ and the browser.
168
172
 
169
173
  ## How it works
170
174
 
@@ -236,8 +240,9 @@ The runtime keeps these promises at every door, so your plugins don't have to.
236
240
  ## In the box
237
241
 
238
242
  Copilotz's own plugins are built the way yours are. Add the ones you need, and change them through
239
- their resources instead of forking them. They come by theme from `copilotz/plugins/<theme>`, and
240
- their front ends from `/web` and `/terminal` beside it.
243
+ their resources instead of forking them. They come by theme from `copilotz/plugins/<theme>`, or one
244
+ at a time (`copilotz/plugins/interfaces/mcp`), and their front ends from `/web` and `/terminal`
245
+ beside the theme.
241
246
 
242
247
  **The doors**
243
248
 
@@ -298,11 +303,35 @@ their front ends from `/web` and `/terminal` beside it.
298
303
  its executors, the store, events and Views, the ways in, and the invariants.
299
304
  - **[Design records](design/)** hold the decisions behind Views, access, work (who, for whom,
300
305
  where), memory and tenancy.
306
+ - **[AGENTS.md](AGENTS.md)** is the short guide for coding agents (Claude Code, Codex, Cursor,
307
+ Gemini) building an app with Copilotz. It ships in the package.
308
+
309
+ ## For coding agents
310
+
311
+ Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot building an app with Copilotz read
312
+ [AGENTS.md](AGENTS.md), which ships in the package. The same guidance comes as an Agent Skill,
313
+ [`copilotz`](skills/copilotz/SKILL.md): short up front, with a walkthrough, the rules and testing in
314
+ files the agent reads when it needs them.
315
+
316
+ ```sh
317
+ npx skills add copilotzhq/copilotz # the skill, for any agent
318
+ /plugin install copilotz --marketplace copilotzhq/copilotz # Claude Code, as a plugin
319
+ codex plugin marketplace add copilotzhq/copilotz # Codex, then:
320
+ codex plugin add copilotz@copilotz
321
+ copilot plugin install copilotzhq/copilotz # GitHub Copilot CLI
322
+ gemini extensions install https://github.com/copilotzhq/copilotz # Gemini CLI
323
+ ```
324
+
325
+ The docs over MCP (`search_docs`, `read_doc`, `agents_guide`) are coming; the plugins will add them
326
+ once they're live, and the skill works without them. Cursor reads the same plugin once it's in the
327
+ Cursor Marketplace; until then, use `npx skills add`.
301
328
 
302
329
  ## Status
303
330
 
304
- Copilotz 1.0 is a release candidate, `1.0.0-rc.34`. It's a new runtime, and it doesn't read 0.x
305
- data. Copilotz 0.x lives on the [`v0`](https://github.com/copilotzhq/copilotz/tree/v0) branch, and
331
+ Copilotz 1.0 is in release candidates:
332
+ [the newest](https://github.com/copilotzhq/copilotz/releases/latest) is on npm's `next` tag
333
+ (`npm install copilotz@next`) and on JSR. It's a new runtime, and it doesn't read 0.x data. Copilotz
334
+ 0.x lives on the [`v0`](https://github.com/copilotzhq/copilotz/tree/v0) branch, and
306
335
  [CHANGELOG.md](CHANGELOG.md) says what each release changed, and how to upgrade.
307
336
 
308
337
  To work on Copilotz itself, see [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -6,7 +6,8 @@
6
6
  * hints, and `search`), observed only while it's open; and the page's own
7
7
  * groups. Items go somewhere, do something (an Action), or open a step of
8
8
  * their own, a list over this one ("Move to…", then a space), opened from
9
- * anywhere with `openPalette(step)`.
9
+ * anywhere with `openPalette(step)`; a step's pick may open one more (the
10
+ * space picked, then whether to move there), and its note may be a View.
10
11
  *
11
12
  * Keyboard first, as a combobox: typing filters, ↑ ↓ (or Ctrl+N, Ctrl+P)
12
13
  * move, Enter chooses, Escape goes back a step or closes it, and Backspace