copilotz 1.0.0-rc.42 → 1.0.0-rc.45

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.
package/AGENTS.md ADDED
@@ -0,0 +1,382 @@
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.45`. 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
+ ## What Copilotz is
13
+
14
+ A runtime for apps that people and AI use alike. You write the app once: its data, what can be done,
15
+ who may do it, and how it shows. People use it on a web page or in a terminal, the app's own agents
16
+ through tools, and outside assistants (ChatGPT, Claude, any MCP client) over MCP. Every way in calls
17
+ the same Actions, under the same rules, and every write is on one record of who did what, for whom.
18
+ It runs on Node 24+, Deno and Bun.
19
+
20
+ ## How Copilotz works, in one minute
21
+
22
+ An app is a **runtime** made of **plugins**. A plugin is plain objects, made of six primitives:
23
+
24
+ | Primitive | What it is |
25
+ | -------------- | ---------------------------------------------------------------------------------------- |
26
+ | **Collection** | documents with a JSON Schema, read and written with the MongoDB collection API |
27
+ | **Action** | something that can be done, by name, with a JSON Schema `input` and an `allow` (who may) |
28
+ | **Processor** | what happens when events happen: it hears the events it names, at least once, in order |
29
+ | **View** | how data shows in one place: text for a model or the terminal, Ink, React for the web |
30
+ | **Resource** | configuration as named plain objects, by kind (`agents`, `tools`, `provider`…) |
31
+ | **Adapter** | one implementation of a port, by name: a model provider's protocol, an email service |
32
+
33
+ A plugin may also declare `routes` and `who` (HTTP), `guard` (rules), `schedules` and a startup
34
+ `check`. Plugins merge in order: a later plugin's resources patch an earlier one's (objects merge,
35
+ `null` removes), and a later View, adapter or route replaces one of the same name.
36
+
37
+ The runtime keeps one contract for every caller:
38
+
39
+ - **Who, for whom, where.** Every call carries an actor, `{ kind, id, for?, in? }`: a person, a
40
+ contact from outside, or an agent working `for` one of them. `in` is where the work is (a space,
41
+ with the access plugin).
42
+ - **The rules, at the data.** Reads come back filtered by what the actor reaches, and writes are
43
+ checked, whichever way the call came in.
44
+ - **The record.** Every write records an event in the same commit, naming its actor.
45
+
46
+ What people often get wrong:
47
+
48
+ - **Two kinds of events.** A collection write records `<collection>.created`, `.updated` or
49
+ `.deleted`. An Action call records `action.started`, then `action.completed` or `action.failed`.
50
+ Callers call Actions; events are what Actions and writes produce.
51
+ - **`runtime.subscribe` hears events; `runtime.observe` keeps a View live**, running it again when a
52
+ commit changes what it read.
53
+ - **Queries read; Actions write.** Named queries and Views never write.
54
+
55
+ Plugins reach each other only through the runtime, by name. One that builds on another says so
56
+ (`requires: ["chat"]`) and imports only that plugin's `contract.ts`, never its code.
57
+
58
+ ## Start a project
59
+
60
+ There's no project generator. Set a project up as the docs' courses do, on Node 24 or newer:
61
+
62
+ ```sh
63
+ mkdir my-app && cd my-app
64
+ npm init -y && npm pkg set type=module
65
+ npm install copilotz@1.0.0-rc.45 react@19 react-dom@19
66
+ npm install -D typescript @types/node @types/react @types/react-dom esbuild
67
+ ```
68
+
69
+ Pin the version: npm's `latest` tag still points at an early release candidate. On Deno, run
70
+ `deno add jsr:@copilotz/copilotz` and map `"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.45"` in
71
+ `deno.json`, so imports read the same.
72
+
73
+ Node runs `.ts` files as they are, so there's no build step. It doesn't run `.tsx`: tests that load
74
+ a `web.tsx` need a loader hook (Getting Started chapter 3 adds one). Copy `tsconfig.json` from
75
+ [Build Compass](https://copilotz.com/docs/build-compass.md), under "What you need": `NodeNext`
76
+ modules, `allowImportingTsExtensions`, `verbatimModuleSyntax`, `erasableSyntaxOnly`, `strict`,
77
+ `noEmit`, and `jsx: "react-jsx"`. The scripts, in `package.json` (add `dev` and `terminal` once
78
+ there's a server and a terminal):
79
+
80
+ ```json
81
+ "scripts": {
82
+ "test": "node --disable-warning=ExperimentalWarning --test --test-timeout=60000 --test-concurrency=1 \"tests/*.test.ts\"",
83
+ "check": "tsc --noEmit -p ."
84
+ }
85
+ ```
86
+
87
+ The layout the docs use:
88
+
89
+ ```text
90
+ app.ts plugins(settings): every plugin, in order. It reads no environment.
91
+ plugins/<name>/
92
+ mod.ts assembles the plugin, and nothing else
93
+ actions.ts … one file per primitive; or collections/, actions/, views/… with one file per
94
+ declaration, as Copilotz's own plugins are laid out
95
+ contract.ts what other plugins may import: shapes and small helpers, never code
96
+ web.tsx its web front end (React Views); terminal.ts, its terminal one
97
+ server.ts the web host: reads the environment, passes settings to plugins()
98
+ tests/kit.ts the app as app.ts makes it, in memory, with a scripted model
99
+ tests/*.test.ts
100
+ .env OPENAI_API_KEY=… (optional; dev and terminal read it: --env-file-if-exists=.env)
101
+ ```
102
+
103
+ **Give the project its own guide.** Write `AGENTS.md` at its root, and `CLAUDE.md` holding the one
104
+ line `@AGENTS.md` (Claude Code reads `CLAUDE.md`, and follows the import). Keep it short and true:
105
+
106
+ ```markdown
107
+ # AGENTS.md
108
+
109
+ This app runs on Copilotz (copilotz@1.0.0-rc.45). Read node_modules/copilotz/AGENTS.md first;
110
+ https://copilotz.com/llms.txt lists the docs, as Markdown.
111
+
112
+ - `npm test` runs every test offline, with a scripted model: run it after each change.
113
+ `npm run check` checks the types.
114
+ - `app.ts` lists the plugins in order; `plugins/<name>/mod.ts` assembles each one.
115
+ - Every change to data is an Action that pages, tools and scripts all call. Access rules live at the
116
+ data (the `shared` resource or a `guard`). Each tool has a `tool:<name>` View.
117
+ ```
118
+
119
+ ## A plugin, end to end
120
+
121
+ A collection, an Action, a View for people and one for the model, a rule, a tool and an agent, in
122
+ `plugins/tasks/mod.ts`:
123
+
124
+ ```ts
125
+ import { defineAction, definePlugin, failure, people } from "copilotz";
126
+ import type { Plugin, ViewContext } from "copilotz";
127
+ import { tool } from "copilotz/plugins/agents";
128
+
129
+ type Task = { _id: string; title: string; in: string };
130
+
131
+ export const tasks: Plugin = definePlugin({
132
+ name: "tasks",
133
+ requires: ["chat", "spaces"],
134
+ collections: {
135
+ task: {
136
+ schema: {
137
+ type: "object",
138
+ properties: { title: { type: "string" }, in: { type: "string" } },
139
+ required: ["title", "in"],
140
+ },
141
+ },
142
+ },
143
+ actions: {
144
+ // The one way to add a task: a button, the agent's tool and a script all call it.
145
+ "task.add": defineAction({
146
+ input: { type: "object", properties: { title: { type: "string" } }, required: ["title"] },
147
+ allow: people,
148
+ run: async (ctx, { title }) => {
149
+ if (!ctx.in) throw failure("invalid", "Add tasks in a space.", { public: true });
150
+ const { insertedId } = await ctx.db.collection("task").insertOne({ title, in: ctx.in });
151
+ return { task: insertedId };
152
+ },
153
+ }),
154
+ },
155
+ views: {
156
+ // Text, for the terminal and for a model. It reads as whoever looks.
157
+ tasks: (_: unknown, ctx: ViewContext) => {
158
+ const found = ctx.db.collection<Task>("task").find({}).value ?? [];
159
+ return found.length ? found.map((t) => `- ${t.title}`).join("\n") : "No tasks.";
160
+ },
161
+ // What a model reads after it calls add_task.
162
+ "tool:add_task": (_call: unknown, ctx: ViewContext) => ctx.show("tasks", {}),
163
+ },
164
+ resources: {
165
+ // The rule, at the data: a task lives in a space (its `in`).
166
+ shared: { task: {} },
167
+ tools: {
168
+ add_task: tool({
169
+ description: "Adds a task to this chat's space",
170
+ input: { type: "object", properties: { title: { type: "string" } }, required: ["title"] },
171
+ run: ({ title }, ctx) => ctx.call("task.add", { title }),
172
+ }),
173
+ },
174
+ agents: {
175
+ helper: { default: true, instructions: "Keep tasks.", model: "helper", tools: ["add_task"] },
176
+ },
177
+ },
178
+ });
179
+ ```
180
+
181
+ `app.ts` lists the plugins and sets the model alias the agent names. Without a key it's
182
+ `"fake/echo"`, Copilotz's offline model: it echoes what it's told, and calls a tool, with no input,
183
+ when the message names it ("add task" for `add_task`).
184
+
185
+ ```ts
186
+ import { definePlugin, type Plugin } from "copilotz";
187
+ import { models } from "copilotz/plugins/models";
188
+ import { chat } from "copilotz/plugins/agents";
189
+ import { access } from "copilotz/plugins/access";
190
+ import { tasks } from "./plugins/tasks/mod.ts";
191
+
192
+ export function plugins(settings: { openai?: string } = {}): Plugin[] {
193
+ const provider = settings.openai ? { openai: { apiKey: settings.openai } } : {};
194
+ const model = { helper: settings.openai ? "openai/gpt-5.4-mini" : "fake/echo" };
195
+ const app = definePlugin({ name: "app-settings", resources: { provider, model } });
196
+ return [models, chat, ...access, tasks, app];
197
+ }
198
+ ```
199
+
200
+ ## Test without an API key: the default loop
201
+
202
+ Run `npm test` after every change, and `npm run check` before you stop. No test needs a key or the
203
+ network. Run the app as `app.ts` makes it, with fakes only where it meets the world: a scripted
204
+ model (below); `createRuntime({ clock: manualClock(Date.now()) })` and `clock.advance(ms)` for time;
205
+ `createRuntime({ fetch })` for what plugins call outside (`ctx.fetch`). A model provider is called
206
+ with the platform's `fetch`, so a fake one is a local server (`serve`, from `copilotz/testing`) set
207
+ as the provider's `baseURL`. `runtime.fetch(new Request(…))` tests HTTP without a port, and
208
+ `await runtime.idle()` waits until nothing is left to run.
209
+
210
+ `tests/kit.ts`:
211
+
212
+ ```ts
213
+ import { createRuntime, definePlugin } from "copilotz";
214
+ import { memoryStore } from "copilotz/stores/memory";
215
+ import type { LlmAdapter, LlmRequest } from "copilotz/plugins/models";
216
+ import { plugins } from "../app.ts";
217
+
218
+ export type Move = string | { tool: string; input?: Record<string, unknown> };
219
+
220
+ /** A model that plays its moves in order, one per call, and keeps what each call sent it. */
221
+ export function scripted(moves: Move[]) {
222
+ const sent: LlmRequest[] = [];
223
+ const adapter: LlmAdapter = {
224
+ async *generate(request) {
225
+ sent.push(request);
226
+ const move = moves.shift();
227
+ if (move === undefined) throw new Error(`The script has no move for call ${sent.length}.`);
228
+ if (typeof move === "string") yield { type: "text", text: move };
229
+ else {
230
+ const call = { id: `call-${sent.length}`, name: move.tool, input: move.input ?? {} };
231
+ yield { type: "tool_call", call };
232
+ }
233
+ },
234
+ };
235
+ return { adapter, sent };
236
+ }
237
+
238
+ /** The app, in memory, with the `helper` alias on a script. */
239
+ export async function start(moves: Move[] = []) {
240
+ const store = memoryStore();
241
+ const helper = scripted(moves);
242
+ const script = definePlugin({
243
+ name: "test-script",
244
+ resources: { provider: { script: { adapter: "script" } }, model: { helper: "script/helper" } },
245
+ adapters: { llm: { script: helper.adapter } },
246
+ });
247
+ const runtime = await createRuntime({ store, plugins: [...plugins(), script] });
248
+ return { runtime, store, helper };
249
+ }
250
+ ```
251
+
252
+ `tests/tasks.test.ts`:
253
+
254
+ ```ts
255
+ import assert from "node:assert/strict";
256
+ import { test } from "node:test";
257
+ import { type Actor, personOf } from "copilotz";
258
+ import { start } from "./kit.ts";
259
+
260
+ test("the agent adds a task for Ana, through the same Action", async () => {
261
+ const { runtime, store, helper } = await start([
262
+ { tool: "add_task", input: { title: "Bo" } },
263
+ "Done.",
264
+ ]);
265
+ try {
266
+ const ana: Actor = { kind: "person", id: "ana" };
267
+ const { space } = await runtime.call<{ space: string }>("space.personal", {}, { actor: ana });
268
+ const here: Actor = { ...ana, in: space };
269
+ await runtime.call("chat.send", { in: space, text: "Add Bo." }, { actor: here });
270
+ await runtime.idle();
271
+ assert.equal(helper.sent[1].messages.at(-1)?.text, "- Bo"); // what the model read
272
+ const made = (await store.events(0)).find((e) => e.type === "task.created");
273
+ assert.equal(personOf(made?.actor), "ana"); // the record: written for Ana…
274
+ assert.equal(made?.actor?.kind, "agent"); // …by the agent
275
+ const seen = await runtime.observe<string>("tasks", {}, { actor: here }).ready;
276
+ assert.deepEqual(seen, { status: "ready", value: "- Bo" }); // what Ana sees
277
+ } finally {
278
+ await runtime.close();
279
+ }
280
+ });
281
+ ```
282
+
283
+ Test what callers may not do as well: call as someone else, and `assert.rejects`.
284
+
285
+ ## Rules: do this, not that
286
+
287
+ - **One Action per change, called from every way in.** A button and a tool call it with `ctx.call`,
288
+ a script with `runtime.call`. Never add a second, looser path. A tool is a thin caller of Actions.
289
+ - **Rules at the data, not in handlers.** Name a collection in the `shared` resource (its documents
290
+ live `in` a space; `part` ties one to another document, as a booking to its chat), or write a
291
+ `guard`. Don't filter by who's asking inside an Action. To keep a collection changing only through
292
+ its Actions, refuse `direct` writes in a `guard`.
293
+ - **Say `allow` on every Action outsiders call:** `people`, `contacts`, `peopleOrContacts`, or
294
+ `inPerson` for what only the person decides (consent, keys, who's in a space, money). It's asked
295
+ of agents too, and of whom they work for. An Action without `allow` is internal.
296
+ - **A View for whatever anyone reads, a model included.** Each tool gets a `tool:<name>` View: short
297
+ text, with ids the model can act on. A failed call's output is its error's words; pass them on,
298
+ don't throw. An MCP server that offers a tool without its View doesn't start.
299
+ - **A View reads in its own body.** A React View reads with `ctx.db` and hands the result to its
300
+ component, so it stays live. Views never write.
301
+ - **Errors for callers are `failure(code, message, { public: true })`.** Only a public failure's
302
+ words reach a caller outside or a model.
303
+ - **Settings are resources, not code.** `app.ts` reads no environment: the server, the terminal or a
304
+ test passes settings in. Agents name a model alias that the app sets.
305
+ - **Writes that must agree go in one `ctx.transaction`.** A refused write rolls it all back. It
306
+ holds the store's writer, so keep slow work out.
307
+ - **Who acts:** `personOf(ctx.actor)`, not `ctx.actor.id` (an agent's is its own). Where: `ctx.in`.
308
+ A tool works where its chat is.
309
+ - **Going past the actor's reach is a named grant,** `ctx.as(grant("…"))`, in trusted code, on the
310
+ record. Keys stay in code: never in Action inputs (they're recorded), never with a model.
311
+ - **Outside effects:** write the intent, call out with its id as the idempotency key (a tool's
312
+ `callId`), then write the result.
313
+ - **Online:** `devSignIn` is for this machine only; Copilotz won't start it with a public origin.
314
+ Keep the `links` secret (32 bytes or more) across restarts, or MCP conversations start over.
315
+
316
+ ## Recipes
317
+
318
+ Each link is a page as Markdown. GS is Getting Started (a salon's bookings, 10 chapters). BC is
319
+ Build Compass (41 chapters, written for an earlier release candidate: check names in the reference).
320
+
321
+ - A plugin: [GS 1](https://copilotz.com/docs/getting-started/01-one-booking.md). People, contacts,
322
+ spaces, the rules: [GS 2](https://copilotz.com/docs/getting-started/02-who-sees-what.md).
323
+ - The web: [GS 3](https://copilotz.com/docs/getting-started/03-its-own-web-page.md),
324
+ [serving on the web](https://copilotz.com/docs/guides/serving-on-the-web.md). An agent and its
325
+ tools: [GS 4](https://copilotz.com/docs/getting-started/04-its-own-agent.md).
326
+ - MCP: [GS 5](https://copilotz.com/docs/getting-started/05-chatgpt-claude-and-gemini-over-mcp.md).
327
+ One test, every way in:
328
+ [GS 6](https://copilotz.com/docs/getting-started/06-the-same-bookings-every-way-in.md).
329
+ - Widgets: [GS 7](https://copilotz.com/docs/getting-started/07-a-widget-in-the-assistant.md). A
330
+ site's chat: [GS 8](https://copilotz.com/docs/getting-started/08-a-chat-on-your-site.md).
331
+ WhatsApp: [GS 9](https://copilotz.com/docs/getting-started/09-whatsapp.md).
332
+ - Shipping (SQLite, PostgreSQL, sign-in by email):
333
+ [GS 10](https://copilotz.com/docs/getting-started/10-shipping-the-salon.md).
334
+ - The prompt and context Views:
335
+ [BC 2](https://copilotz.com/docs/build-compass/part-1-an-agent-of-your-own/02-north-in-your-terminal.md),
336
+ [BC 4](https://copilotz.com/docs/build-compass/part-2-your-own-plugins/04-today-every-turn.md).
337
+ - A Processor:
338
+ [BC 6](https://copilotz.com/docs/build-compass/part-2-your-own-plugins/06-chats-that-name-themselves.md).
339
+ Transactions:
340
+ [BC 9](https://copilotz.com/docs/build-compass/part-3-the-board/09-the-boards-data-and-actions.md).
341
+ - Schedules and a manual clock:
342
+ [BC 27](https://copilotz.com/docs/build-compass/part-8-skills-and-routines/27-routines-on-a-schedule.md).
343
+ Fakes at the edges:
344
+ [BC 31](https://copilotz.com/docs/build-compass/part-10-testing/31-fakes-at-the-edges.md).
345
+ - Scripts over REST: [REST and the client](https://copilotz.com/docs/guides/rest-and-the-client.md).
346
+ Many orgs: [many orgs](https://copilotz.com/docs/guides/many-orgs.md).
347
+ - Every entry point, option, event and context field:
348
+ [reference](https://copilotz.com/docs/reference.md). Each of Copilotz's plugins (`chat`, `spaces`,
349
+ `mcp`…): [plugins](https://copilotz.com/docs/reference/plugins.md). How it runs:
350
+ [architecture](https://copilotz.com/docs/architecture.md).
351
+
352
+ ## Entry points
353
+
354
+ The same names on npm (`copilotz/…`) and JSR (`@copilotz/copilotz/…`); the package's `package.json`
355
+ lists them all. Besides those above: `copilotz/stores/sqlite` and `copilotz/stores/postgres`
356
+ (stores), `copilotz/plugins/interfaces` (`mcp`, `api`, `whatsapp`, `voice`, `webLines`),
357
+ `copilotz/web` (the web host, `web`), `copilotz/web/server` (`webPage`), `copilotz/web/node`
358
+ (`listen`, `serve`, `bundle`), `copilotz/terminal` (`terminal`) and `copilotz/testing`. Front ends
359
+ sit beside each theme (`copilotz/plugins/agents/web` has `chatWeb`). Product packages ship at the
360
+ same version: `@copilotz/work` (`boards`, `documents`), `@copilotz/team`, `@copilotz/directory` and
361
+ `@copilotz/billing`.
362
+
363
+ ## Working on Copilotz itself
364
+
365
+ [CONTRIBUTING.md](CONTRIBUTING.md) has the rest. The checks:
366
+
367
+ ```sh
368
+ deno task check && deno task test # types, the suite (COPILOTZ_TEST_POSTGRES_URL: PostgreSQL)
369
+ npm install && npm test # the suite on Node 24 (bun test --timeout 60000 on Bun)
370
+ deno fmt --check # the format CI checks
371
+ npm run build && node scripts/npm/smoke.ts && deno publish --dry-run # the packages
372
+ ```
373
+
374
+ - The runtime imports nothing outside it. A plugin imports the runtime, the hosts' toolkits, its own
375
+ files and other plugins' `contract.ts` (`testing/boundaries.test.ts`).
376
+ - A plugin is `plugins/<theme>/<name>/`, by primitive, one file per declaration; `mod.ts` only
377
+ assembles it. Tests sit in `plugins/<theme>/tests/`. Factories and plain data, no classes.
378
+ - After changing a plugin, `deno run -A scripts/describe.ts --docs` remakes its reference page.
379
+ After changing docs, `python3 scripts/docs-index.py && deno fmt docs`.
380
+ - `testing/agents-md.test.ts` checks this file's imports, links and version;
381
+ `node scripts/version.ts <version>` moves its version with the rest. Releases are tags the
382
+ maintainers push: don't tag or publish.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,24 @@
1
+ ## 1.0.0-rc.45 — 2026-11-12
2
+
3
+ - **AGENTS.md, a guide for coding agents.** Claude Code, Codex, Cursor or Gemini building an app
4
+ with Copilotz finds it in the package (`node_modules/copilotz/AGENTS.md`, and in
5
+ `@copilotz/copilotz` on JSR): how Copilotz works, how to set up a project and test it offline with
6
+ a scripted model, the rules the docs insist on, and links to the docs' pages as Markdown. It has
7
+ each project keep an `AGENTS.md` of its own, with a `CLAUDE.md` that imports it.
8
+ `testing/agents-md.test.ts` checks that what it imports, links and installs is there, and the npm
9
+ smoke test that the installed package has it.
10
+
11
+ ## 1.0.0-rc.44 — 2026-11-12
12
+
13
+ (rc.43 was tagged but never published: a file wasn't formatted. This is it.)
14
+
15
+ - **The app opens in Firefox again.** Once its service worker was installed, every page load
16
+ answered `{"error":"Not found"}`: the worker passes a page's own request on, and Firefox sends
17
+ that as `Sec-Fetch-Mode: same-origin` rather than `navigate`, which the page took for a script's
18
+ `fetch`. A request whose destination is a document (`Sec-Fetch-Dest: document`, or `iframe`) is
19
+ now a page too, so browsers that already have the worker are fixed by the server alone; a script's
20
+ `fetch` still gets a 404.
21
+
1
22
  ## 1.0.0-rc.42 — 2026-11-11
2
23
 
3
24
  (rc.41 was tagged but never published: a test failed on Node. This is it.)
package/README.md CHANGED
@@ -162,7 +162,7 @@ OPENAI_API_KEY=sk-… node salon.ts # or bun salon.ts, or deno run -A salon.t
162
162
  ```
163
163
 
164
164
  On Deno, map the name `copilotz` in `deno.json`
165
- (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.42"`) so the imports read the same everywhere.
165
+ (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.45"`) so the imports read the same everywhere.
166
166
  Copilotz runs on Node, Deno and Bun, and it's built on web standards for Cloudflare Workers and the
167
167
  browser.
168
168
 
@@ -298,6 +298,8 @@ their front ends from `/web` and `/terminal` beside it.
298
298
  its executors, the store, events and Views, the ways in, and the invariants.
299
299
  - **[Design records](design/)** hold the decisions behind Views, access, work (who, for whom,
300
300
  where), memory and tenancy.
301
+ - **[AGENTS.md](AGENTS.md)** is the short guide for coding agents (Claude Code, Codex, Cursor,
302
+ Gemini) building an app with Copilotz. It ships in the package.
301
303
 
302
304
  ## Status
303
305
 
@@ -144,14 +144,17 @@ ${look(theme)}${installable(title)}<title>${title}</title>
144
144
  </html>`;
145
145
  };
146
146
  /**
147
- * Whether a GET is a browser navigating (`Sec-Fetch-Mode: navigate`), or,
148
- * from one that doesn't say, one asking for a page (`Accept` with HTML, or
149
- * anything, or none): the page is for them; a script's `fetch` gets a 404.
147
+ * Whether a GET is a browser navigating (`Sec-Fetch-Mode: navigate`, or a
148
+ * page's own request passed on by the service worker, which some browsers
149
+ * send as `same-origin`: its destination is still a document), or, from one
150
+ * that doesn't say, one asking for a page (`Accept` with HTML, or anything,
151
+ * or none): the page is for them; a script's `fetch` gets a 404.
150
152
  */
151
153
  const navigating = (request) => {
152
154
  const mode = request.headers.get("sec-fetch-mode");
155
+ const dest = request.headers.get("sec-fetch-dest");
153
156
  if (mode !== null)
154
- return mode === "navigate";
157
+ return mode === "navigate" || dest === "document" || dest === "iframe";
155
158
  const accept = request.headers.get("accept");
156
159
  return accept === null || accept.includes("text/html") || accept.includes("*/*");
157
160
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "copilotz",
3
- "version": "1.0.0-rc.42",
3
+ "version": "1.0.0-rc.45",
4
4
  "description": "Copilotz: one runtime for Node, Deno, Bun, Cloudflare Workers and the browser.",
5
5
  "keywords": [
6
6
  "agents",
@@ -193,6 +193,7 @@
193
193
  "./package.json": "./package.json"
194
194
  },
195
195
  "files": [
196
+ "AGENTS.md",
196
197
  "CHANGELOG.md",
197
198
  "LICENSE",
198
199
  "README.md",
@@ -1,2 +1,2 @@
1
1
  /** The computer program's version, as `computer.info` and `--version` say it, and its builds are named. */
2
- export declare const VERSION = "1.0.0-rc.42";
2
+ export declare const VERSION = "1.0.0-rc.45";
@@ -1,2 +1,2 @@
1
1
  /** The computer program's version, as `computer.info` and `--version` say it, and its builds are named. */
2
- export const VERSION = "1.0.0-rc.42";
2
+ export const VERSION = "1.0.0-rc.45";
@@ -14,7 +14,7 @@
14
14
  *
15
15
  * ```ts
16
16
  * plugins: [...plugins, await computerDownloads()]
17
- * plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.42" })]
17
+ * plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.45" })]
18
18
  * plugins: [...plugins, await computerDownloads({ url: "https://downloads.example.com/computer/" })]
19
19
  * ```
20
20
  */