acrylblends 1.1.0 → 1.3.0

package/plugins/plugin-share/pulled-records.ts

@@ -0,0 +1,70 @@
+/**
+ * What an app remembers about the plugins it pulled: their source and digests, in the `plugin-share` row's config of `blend.yaml`. A row's config is
+ * resolved into `blend.lock.json` too, so the lock records them with no new format, and a copy of the app can fetch exactly the same bytes. Pure text
+ * to text; comments and the person's formatting stay.
+ */
+import { isMap, isSeq, parseDocument } from 'yaml'
+
+export const ROW = 'plugin-share'
+
+export interface PulledRecord {
+  /** `github:<owner>/<repo>@<version>` or an https address: something another machine can fetch. */
+  readonly source: string
+  /** The sha512 of the release file. */
+  readonly integrity: string
+  /** The sha256 of the plugin's content. */
+  readonly digest: string
+}
+
+const isRecord = (value: unknown): value is PulledRecord => {
+  const record = value as Partial<Record<keyof PulledRecord, unknown>> | null
+  return (
+    typeof record?.source === 'string' &&
+    typeof record.integrity === 'string' &&
+    typeof record.digest === 'string'
+  )
+}
+
+/** The plugins this definition remembers pulling. */
+export function pulledRecords(text: string): Readonly<Record<string, PulledRecord>> {
+  const rows = (parseDocument(text).toJS() as { spec?: { rows?: unknown } } | null)?.spec?.rows
+  if (!Array.isArray(rows)) return {}
+  const pulled = (
+    rows.find((row: { name?: unknown }) => row?.name === ROW) as
+      | { config?: { pulled?: unknown } }
+      | undefined
+  )?.config?.pulled
+  if (typeof pulled !== 'object' || pulled === null) return {}
+  return Object.fromEntries(
+    Object.entries(pulled).filter(([, record]) => isRecord(record)),
+  ) as Record<string, PulledRecord>
+}
+
+/**
+ * The definition with one plugin's record written, or taken out when `record` is undefined. Unchanged when it has no `plugin-share` row: an app
+ * composed without the row has nowhere to remember.
+ */
+export function withPulledRecord(
+  text: string,
+  name: string,
+  record: PulledRecord | undefined,
+): string {
+  const document = parseDocument(text)
+  const rows = document.getIn(['spec', 'rows'])
+  if (!isSeq(rows)) return text
+  const row = rows.items.find((item) => isMap(item) && item.get('name') === ROW)
+  if (!isMap(row)) return text
+  if (record === undefined) {
+    if (!row.hasIn(['config', 'pulled', name])) return text
+    row.deleteIn(['config', 'pulled', name])
+    const left = row.getIn(['config', 'pulled'])
+    if (isMap(left) && left.items.length === 0) row.deleteIn(['config', 'pulled'])
+    const config = row.get('config')
+    if (isMap(config) && config.items.length === 0) row.delete('config')
+  } else {
+    row.setIn(['config'], row.get('config') ?? document.createNode({}))
+    if (!row.hasIn(['config', 'pulled'])) row.setIn(['config', 'pulled'], document.createNode({}))
+    row.setIn(['config', 'pulled', name], document.createNode(record))
+  }
+  return String(document)
+}

package/shared/AGENTS.core.md

@@ -19,35 +19,52 @@ The docs write `import { Acryl } from 'acrylblends'` and `from 'acrylblends/<sub
 
 **JSX: write `.tsx`.** The scripts in `package.json` run Node.js with `--import ./plugins/acryl-node-server/src/register.ts`, which compiles `.tsx` files with this app's own `typescript`; `tsconfig.json` sets `jsx: react-jsx` and `jsxImportSource: #acryl-jsx`, which `package.json`'s `imports` maps to the vendored runtime in `plugins/acryl-router`. See `src/about.tsx` (blank template) for a page and `test/app.test.ts` for how it is tested. Render a component with `.toString()` and return it with `c.html(...)`; import `jsx`, `Fragment` and the types from `../plugins/acryl-router/src/core/jsx/index.ts` when you need them. A command that starts the app without those scripts (a bare `node src/main.ts`) cannot load a `.tsx` file. Without a build step you can write the call JSX compiles to instead: `jsx('h1', { class: 'title' }, 'Hello')`, children after the props.
 
-**A plugin you install into the running app** (`.acryl/bin/acryl plugin add plugins/<name>`) **imports the framework by its package name**: `import { Acryl } from 'acrylblends'` (and `acrylblends/<subpath>`, for example `acrylblends/helpers`). `acrylblends` and `acrylblends/<subpath>` resolve to the same files as the relative paths above, and the plugin is checked in a staging copy where a relative path like `../plugins/acryl-router/src/index.ts` may not resolve (a plugin that wrote it failed its first install). Plugins that `src/app.ts` imports at start-up keep using the relative paths. `App` is the
+**A plugin imports the framework by its package name**: `import { Acryl } from 'acrylblends'` (and `acrylblends/<subpath>`, for example
+`acrylblends/helpers`), which resolves to the same files as the relative paths above. Only files in `src/` use the relative paths. `App` is the
 deprecated name of `Acryl`.
 
-## How a feature is built
+## How a feature is built: a plugin of its own
 
-Routes are an ordinary `Acryl` app that a plugin mounts once with `ctx.router.route(prefix, app)`. The mount belongs to the plugin and goes away when it unloads.
+**Every feature is a Cordis plugin: a folder `plugins/<name>/` with an `index.ts`, plus its row in `blend.yaml`.** Never wire a feature into
+`src/app.ts`, `src/routes.ts` or `src/frame.ts`, and never import it there: the row is what starts it. Settings > Plugins lists it, switches it off
+and on (`disabled: true` on its row) and shares it, and every version of the app carries it.
+
+When your prompt names this app's builder docs (`acryl_plugin_docs`), read the doc for your task and its verified example before you write the
+plugin; they are this section in full.
 
 ```ts
+// plugins/notes/index.ts
 import type { Context } from '@deepseek-ai/cordis'
-import { Acryl, HTTPException } from '../plugins/acryl-router/src/index.ts'
-import { schemaValidator, type StandardSchema } from '../plugins/acryl-router/src/helpers/index.ts'
+import { Acryl } from 'acrylblends'
 
-export const name = 'notes'               // a plugin's name; blend.yaml refers to it
-export const inject = ['router']          // services it needs
+export const name = 'notes'               // the folder's name; blend.yaml's row names it
+export const inject = ['router']          // services it needs (a name nobody provides leaves it waiting, silently)
 export function apply(ctx: Context) {
   const app = new Acryl()
     .get('/', (c) => c.json({ ok: true }))
-    .get('/:id', (c) => c.json({ id: c.req.param('id') }))
-    .post('/', schemaValidator('json', NewNote), (c) => c.json(c.req.valid('json'), 201))   // NewNote is a Standard Schema
+    .post('/', async (c) => c.json(await c.req.json(), 201))
   ctx.router.route('/notes', app)         // build the whole app first: routes added after route() are not served
 }
 ```
 
-- A small route goes on the `App` in `src/routes.ts`. A new feature is a new plugin file: add it to `registry` in `src/app.ts`, add a row
-  (`- id: notes` / `name: notes`) to `blend.yaml` before the `acryl-node-server` row, and pass runtime values (a data file) as its config in `createApp`.
-- State, when `plugins/acryl-state` exists: `const cell = ctx.state.cell<T>('notes.list', initial)` (add `'state'` to `inject`), then
-  `cell.get()`, `cell.set(value)`, `cell.update(fn)` and `cell.subscribe(fn)` (returns the unsubscribe). Every cell is also served as JSON at `/api/state/<key>`
-  and streamed at `/api/state/<key>/events`.
-- Test a route without a socket: `await ctx.router.request('/notes')`, or boot the app as `test/app.test.ts` does and use `fetch`.
+```yaml
+# blend.yaml, before the `acryl-node-server` row
+    - id: notes
+      name: notes
+```
+
+- Routes are an ordinary `Acryl` app that the plugin mounts once with `ctx.router.route('/notes', app)`; the mount belongs to the plugin and goes
+  away when it unloads. The frame that hosts the app in development adds its canvas prefix to every route a plugin mounts: the same plugin
+  answers `/notes` under `npm start` and `/app/notes` in the canvas. Write the app's own path, and fetch it from a page by that path
+  (`fetch('/notes')`); never put the frame's prefix in a route or a URL.
+- A plugin's name is its folder's name. It imports only `@deepseek-ai/cordis` (types), `acrylblends`, `node:*`, its own files, and type-only
+  `import type {} from '../home/index.ts'` / `'../instance/index.ts'` for the services those give `ctx`. Never guess another path.
+- Something on the first screen (blank template): add `'home'` to `inject` and register a widget in an effect,
+  `ctx.effect(() => ctx.home.widget({ id: 'notes', title: 'Notes', render: () => '<ul>...</ul>' }))`; it leaves the page with the plugin.
+- Data that must survive a restart goes in a file in `ctx.appInstance.home` (add `'appInstance'` to `inject`), written whole through a temporary
+  file and a rename; a variable starts again at every reload. With `plugins/acryl-state`: `ctx.state.cell<T>('notes.list', initial)` (add
+  `'state'` to `inject`), served as JSON at `/api/state/<key>` and streamed at `/api/state/<key>/events`.
+- Test it in `test/<name>.test.ts` without a socket: boot the app as `test/app.test.ts` does and use `app.root.router.request('/notes')`.
 
 ## Things that surprise people
 
@@ -58,7 +75,10 @@ export function apply(ctx: Context) {
 - Handlers get the request as `c.req`: `c.req.param('id')`, `c.req.query('q')`, `await c.req.json()`, `c.req.raw` for the Web `Request`.
 - A server-sent stream is `streamSSE(c, async (stream) => { await stream.writeSSE({ data: JSON.stringify(x) }) ... })`; call `stream.onAbort(cleanup)`.
 - `npm run dev` restarts the app whenever a file changes.
+- **In ACRYL's chat, the running app is the process that runs you: never stop, kill or restart it.** A saved change in `blend.yaml`, `src/` or `plugins/` reloads the app by itself and the page beside you shows it; a new plugin starts with that reload once its folder and its row are there. If a change does not show, the reload failed: read the error line in the frame's bar or `look` again, don't restart. `.acryl/bin/acryl plugin ...` is not available there, and is not needed.
 
 ## Before you say you are done
 
-`npm test` and `npm run check` (type-check) both pass. Put tests in `test/`, written with `node:test` like `test/app.test.ts`.
+`npm test` and `npm run check` (type-check) both pass, and `.acryl/bin/acryl look` shows the feature on the page. Put tests in `test/`, written
+with `node:test` like `test/app.test.ts`. A failure names the file and the line: fix the cause in the plugin, never the test, and never move the
+feature into `src/` to get around it.

package/shared/skills/acryl-add-ui/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: acryl-add-ui
+description: Use when a feature of __APP_NAME__ needs something the person sees - a widget on the first screen, a page of its own, a button or a form.
+---
+# Add UI to the app
+
+`<docs>` is the builder docs folder that the `acryl_plugin_docs` section of your prompt names (paths below are under it).
+
+The app's UI is HTML its plugins serve. Two places:
+
+- **On the first screen (the canvas)**: a widget. Read `<docs>/docs/extending/home-widget.md` completely and the example
+  `<docs>/example-plugins/packages/home-widget-basic/`. Add `'home'` to `inject`, register the widget inside `ctx.effect`, escape every value
+  you put into its HTML, prefix its element ids with the plugin's name, and let its `<script type="module">` fetch the plugin's own routes by the
+  app's path (`fetch('/<name>/items')`, never `/app/...` or `./...`).
+- **A page of its own**: read `<docs>/docs/extending/routes-and-pages.md` and the example `route-page-basic`; link to it from the widget.
+
+Decide where the data lives first (`<docs>/docs/extending/state.md`): what the person types must survive a reload, so it goes in a file in
+`ctx.appInstance.home`, never only in a variable or in `localStorage`. Then build it with the acryl-build-plugin workflow and check the page with
+`.acryl/bin/acryl look` and `act`.

package/shared/skills/acryl-app/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: acryl-app
+description: How the __APP_NAME__ app is put together - its blend.yaml rows, its plugins/ folder and src/ - and how to change it, run it and check it through the door. Use before adding a feature, a route, a plugin or a dependency to this app, and before saying the work is done.
+---
+
+# Working in __APP_NAME__
+
+1. **Read first.** `AGENTS.md` (the same text as `CLAUDE.md`) is the app's guide. The framework's API is in `docs/framework/`: start at `docs/framework/README.md`, and `docs/framework/api/summary.md` is the one-page summary. Parts the docs mark "not yet available" are not in this app.
+2. **The app is data plus code.** `blend.yaml` is the blueprint: which plugins (rows) the app mounts, in what order, with what config. `src/app.ts` is the runtime: a row's `name` is a library plugin its `registry` imports or a folder `plugins/<name>/` of the app's own, and `compose` starts them in row order. `src/routes.ts` is the app's own `Acryl` app (its page and API). A plugin the app owns is a folder `plugins/<name>/`.
+3. **Make the change small.** A route is a handler on the app's `Acryl` app mounted with `ctx.router.route('/', app)`; test it with `await app.request('/path')`. Write the app's own paths: the frame that hosts the app adds its canvas prefix to every plugin route (`/board` answers `/board` under `npm start` and `/app/board` in the canvas), so never put the prefix in a route. Every feature is a Cordis plugin: a `plugins/<name>/` folder plus its row in `blend.yaml` (see the acryl-build-plugin skill); `src/app.ts` and `src/routes.ts` are never touched for a feature. `npx acrylblends add <name>` copies a library plugin there.
+4. **Defaults are swappable.** The database, the key-value store, the server and the window are plugins behind ports; the table "Defaults you can swap" in `AGENTS.md` names each default and where it is swapped. Never reach around a port to a driver: `npx acrylblends check-deps` fails the check.
+5. **Look at the running app.** In development the app writes `.acryl/bin/acryl`: `acryl brief` says what this folder runs, `acryl look` shows the open page as text with refs, and `acryl act click|type|select|press|scroll|wait|navigate|reload` acts on it. Look again before each act, because the refs change. This is the app's control surface: use it instead of guessing what the page shows.
+6. **Done means checked.** `npm test` passes, and the change shows in the running app. No secret goes in a file or in `git status`: keys come from environment variables.

package/shared/skills/acryl-build-plugin/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: acryl-build-plugin
+description: Use when the person asks for a new feature, widget, page, tool, list or integration in __APP_NAME__ (build a plugin). The workflow from reading the docs to a feature that is on the page and checked.
+---
+# Build a feature as a plugin
+
+`<docs>` is the builder docs folder that the `acryl_plugin_docs` section of your prompt names (paths below are under it).
+
+1. Read `<docs>/docs/start-here/this-app.md` completely: what the app is made of, the rule (a feature is `plugins/<name>/` plus its row in
+   `blend.yaml`, never code in `src/`) and the imports a plugin may use.
+2. Pick the docs for the feature from `<docs>/docs/README.md` (read-it-when column): routes and pages, a home widget, state. Read each one
+   completely and follow its links.
+3. Open the closest verified example in `<docs>/example-plugins/README.md` and read every file of it. Copy it to `plugins/<name>/` and change
+   it: `name` equals the folder's name, `inject` names only services that exist (`router`, `home`, `appInstance`, or a row's service).
+   Never guess a plugin's shape or an import path from memory.
+4. Add its row to `blend.yaml` before the `acryl-node-server` row (`- id: <name>` / `name: <name>`). Do not touch `src/app.ts`,
+   `src/routes.ts` or `src/frame.ts`.
+5. Write `test/<name>.test.ts` like `test/app.test.ts`: the widget is on the first screen, the routes answer, the data survives a remount.
+6. Verify (`<docs>/docs/start-here/verify-before-done.md`): `npm test`, `npm run check`, then `.acryl/bin/acryl look` shows it. Fix the
+   cause of the first failure and run again.
+7. Tell the person what you built, where it is on the page, and that it is the plugin `<name>` in Settings > Plugins. Never claim it works
+   before the three checks agree.

package/shared/skills/acryl-change-plugin/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: acryl-change-plugin
+description: Use when the person asks you to change, improve, extend or restyle a feature or plugin that already exists in __APP_NAME__.
+---
+# Change a plugin
+
+`<docs>` is the builder docs folder that the `acryl_plugin_docs` section of your prompt names (paths below are under it).
+
+1. Find it: the feature's folder in `plugins/` and its row in `blend.yaml` (Settings > Plugins lists them too). If no plugin has it, it may be
+   part of the app's own page in `src/`; say so instead of guessing.
+2. Read every file of the plugin before editing, and the doc for what you change (`<docs>/docs/README.md`).
+3. Edit its folder. The frame reloads the app 300 ms after the change; a change to `inject` or the row's config reloads it the same way.
+   Keep its name: a new name is a new plugin with a new row.
+4. Update its test, then verify (`<docs>/docs/start-here/verify-before-done.md`) and say what changed and that it is on the page.

package/shared/skills/acryl-diagnose-plugin/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: acryl-diagnose-plugin
+description: Use when a feature of __APP_NAME__ misbehaves and the cause is unclear - nothing shows, buttons do nothing, data is lost, the top bar says Not reloaded, or a check fails in a way you do not understand.
+---
+# Diagnose a plugin methodically
+
+`<docs>` is the builder docs folder that the `acryl_plugin_docs` section of your prompt names (paths below are under it).
+
+Read `<docs>/docs/start-here/troubleshooting.md`. Then, in order: (1) `npm test` and `npm run check`, and read the first error completely
+(it names the file and the line); (2) `.acryl/bin/acryl look` to see what the page shows now; (3) check the plugin's row in `blend.yaml`
+(present, not `disabled: true`, the folder's name) and that every name in `inject` is provided (a missing service leaves the plugin waiting
+without an error); (4) change ONE thing, run the checks again, look again. Never guess a state you have not read. If the same cause survives two
+fixes, stop and tell the person what you observed.

package/shared/skills/acryl-fix-plugin/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: acryl-fix-plugin
+description: Use when a plugin you wrote in __APP_NAME__ fails - npm test or npm run check fails, the top bar says "Not reloaded", or the feature is not on the page.
+---
+# Fix a plugin that does not work
+
+`<docs>` is the builder docs folder that the `acryl_plugin_docs` section of your prompt names (paths below are under it).
+
+Read `<docs>/docs/start-here/troubleshooting.md` and `<docs>/docs/start-here/verify-before-done.md`. The error is the real cause: read it
+first. `Cannot find module` is a guessed import (a plugin imports only `@deepseek-ai/cordis`, `acrylblends`, `node:*` and its own files);
+`exports the plugin name` means `name` differs from the folder; `no plugin '<name>' in the app's registry` means the row names a folder that is
+not there; a plugin with no error and nothing on the page waits for a service its `inject` names. Fix the cause in the plugin (never the test,
+never by moving the feature into `src/`), run the checks again, and only then tell the person it works.

package/shared/skills/acryl-remove-plugin/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: acryl-remove-plugin
+description: Use when the person asks to remove, delete, switch off, hide or undo a feature or plugin of __APP_NAME__.
+---
+# Switch off or remove a plugin
+
+`<docs>` is the builder docs folder that the `acryl_plugin_docs` section of your prompt names (paths below are under it). Read `<docs>/docs/delivery/switch-and-remove.md`.
+
+Find the exact plugin in `plugins/` and its row in `blend.yaml` (never guess the name). To hide it for now, switch it off: `disabled: true` on
+its row (the switch in Settings > Plugins does the same); everything stays and it comes back when switched on. To remove it, and only when the
+person clearly asked: delete its row, its folder and its test; its data in `.acrylblends/` stays unless they ask. Check with `npm test` and
+`.acryl/bin/acryl look` that it is gone before you say so. Only touch the plugin the person named.

package/shared/skills/acryl-share-plugin/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: acryl-share-plugin
+description: Use when the person wants to share, publish or version a plugin of __APP_NAME__, save or restore a version of the app, or make a blueprint of it.
+---
+# Share a plugin, versions and blueprints
+
+`<docs>` is the builder docs folder that the `acryl_plugin_docs` section of your prompt names (paths below are under it). Read `<docs>/docs/delivery/share-and-snapshot.md`.
+
+The app is `blend.yaml` + `plugins/` + `src/`, and every way it is kept or passed on reads exactly that. A version is a commit the frame
+makes after a turn that changed files; the left panel lists and restores them. A plugin is shared from Settings > Plugins > Share on its row: it is
+packaged for the CordisPlugins registry and published to a GitHub repository of the person's own account, with their own `gh` login.
+
+1. Make sure it works first (`<docs>/docs/start-here/verify-before-done.md`) and give it a doc comment whose first sentence says what it does.
+2. Sharing sends the person's work out under their name: never share, push or publish yourself. Tell them to press **Share** on the plugin's row.
+   Never ask for or handle a token.
+3. A fix to a plugin that was already shared needs a new version: Share again offers the next patch version and asks first.

package/shared/skills/cordis-plugin/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: cordis-plugin
+description: Add a Cordis plugin to __APP_NAME__ - a plugins/<name>/ folder with name, inject, apply and an optional check, its routes as an Acryl app, how its blend.yaml row mounts it, and how to verify it. Use when a feature should be its own plugin, or when asked to extend the app.
+---
+
+# Adding a Cordis plugin
+
+A plugin is a folder `plugins/<name>/` with an `index.ts` exporting `name` (its id), `inject` (the services it needs) and `apply(ctx)`. Everything it acquires belongs to one `ctx.effect(...)`, so unloading the plugin or stopping the app releases it.
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { Acryl } from 'acrylblends'
+
+export const name = 'due-dates'
+export const inject = ['router']
+
+export function apply(ctx: Context): void {
+  const app = new Acryl().get('/due-dates', (c) => c.json({ ok: true }))
+  ctx.router.route('/due-dates', app)
+}
+```
+
+- **Routes** are an `Acryl` app mounted with `ctx.router.route('/due-dates', app)`; removing the plugin removes them. Write the app's own path: the frame that hosts the app in development adds its canvas prefix, so the same route answers `/due-dates` under `npm start` and `/app/due-dates` in the canvas. Never put the frame's prefix in a plugin's route. Import the framework by name (`acrylblends`, `acrylblends/body-limit`); never guess a relative path into another plugin.
+- **State** lives in cells: `ctx.state.cell('due-dates.tasks', [])`. A page follows one with `watch` from `/api/state/client.js`, never with an `EventSource`, and never by polling what `watch` already pushes.
+- **Its row starts it.** Add a row to `blend.yaml` (`- id: <name>` and `name: <name>`, before the `acryl-node-server` row); `src/app.ts` finds the folder by that name, so it is never imported there. `disabled: true` on the row switches it off (Settings > Plugins does the same). `.acryl/bin/acryl plugin add plugins/<name>` installs a folder without a row live, for trying it; a folder with a row is the app's.
+- **Check it.** `npm test` and `npm run check` must pass. With the app running, use the door: `.acryl/bin/acryl look` reads the page as text with refs and `acryl act ...` acts on it; an install or reload shows the new feature in the page.

package/templates/agent/.gitattributes

@@ -0,0 +1,2 @@
+# Every checkout has the same line endings, on every OS. A plugin's digest counts every byte, so a CRLF checkout would make it a different plugin.
+* text=auto eol=lf

package/templates/agent/AGENTS.md

@@ -5,7 +5,7 @@ Besides `src/routes.ts`, the app runs an agent (`POST /ask`) that can write plug
 rollback; `GET /extensions` and `GET /tasks` show what it did. A plugin there is a folder with an `index.ts` exporting `name`, `inject`, `apply(ctx)`
 and an optional `check(ctx)` that receives the plugin's own context (so `ctx.router` reads as in `apply`). It may import `acryl-router`.
 
-**Write an extension, not a row.** A feature you build while the app runs is a folder `plugins/<name>/` installed with `.acryl/bin/acryl plugin add plugins/<name>` (the `extensions` plugin loads it again at every start). Add a row to `blend.yaml` and an entry to the `registry` of `src/app.ts` only when the person asks for a plugin that is part of the app itself. Both kinds may import the framework by name (`acrylblends`, `acrylblends/body-limit`, `acryl-router`); a row's relative imports of its sibling plugins also work.
+**Write an extension, not a row.** A feature you build while the app runs is a folder `plugins/<name>/` installed with `.acryl/bin/acryl plugin add plugins/<name>` (the `extensions` plugin loads it again at every start). Add a row to `blend.yaml` (`- id: <name>` / `name: <name>`; `src/app.ts` finds the folder by that name) only when the person asks for a plugin that is part of the app itself. Both kinds may import the framework by name (`acrylblends`, `acrylblends/body-limit`, `acryl-router`); a row's relative imports of its sibling plugins also work.
 
 **Drive the app you build.** `.acryl/bin/acryl look` reads the open page as text with refs, and `acryl act click|type|press|scroll|wait --ref <ref>` presses its buttons, opens its sidebars and fills its forms (look again before each act: the refs change). `act navigate --path /settings` goes to another page of the app; a path the app does not serve answers `404 at /nope` and the window shows a 404 page, so navigate on from there. In the desktop app (`npm run desktop`) the app's windows and menu are verbs too: `acryl window list`, `acryl window open --path /settings`, `acryl look --window <id>` (and `act ... --window <id>`) to drive that window's page, `acryl window resize|focus|close --id <id>`, `acryl menu list` and `acryl menu click --path "File>New Note"`. Closing the last window and Quit end the desktop app, so they need `--force`: do not use it unless the person asks. The app has a `/settings` page already (the appearance: system, light or dark, kept in the browser) and the desktop app's menu has a Settings item that opens it; add a person's other settings to that page, not to a new one, so `acryl menu click --path "File>Settings..."` and `acryl window open --path /settings` keep opening them (on macOS the item is in the application menu). Without a desktop app these answer "no desktop window is attached; run npm run desktop".
 

package/templates/agent/blend.yaml

@@ -24,10 +24,13 @@ spec:
       name: tasks
       config:
         store: "{{parameters.taskStore}}"
+    # The model the agent asks at each step: a scripted offline one until a provider key is set.
     - id: model
       name: model
+    # The tools the agent can call, each with what it does and the input it takes.
     - id: tools
       name: tools
+    # Long-term memory for the agent.
     - id: memory
       name: memory
     - id: agent
@@ -46,11 +49,14 @@ spec:
         approval: "{{parameters.approval}}"
     - id: builder
       name: builder
+    - id: plugin-share
+      name: plugin-share
     - id: save
       name: save
     # The panel: a chat button on every page in development (the app's own agent, or Codex, Claude or pi started in this folder). It starts nothing in production.
     - id: agent-panel
       name: agent-panel
+    # The app's own pages and API.
     - id: routes
       name: routes
     - id: server

package/templates/agent/gitignore

@@ -1,3 +1,4 @@
 node_modules/
 .acrylblends/
 .acryl/
+package-lock.json

package/templates/agent/package.json

@@ -16,6 +16,7 @@
     "test": "node --import ./plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
     "check": "tsc --noEmit",
     "lock": "node plugins/manifest/lock.ts",
+    "snapshot": "node plugins/manifest/snapshot.ts",
     "save": "node plugins/save/cli.ts",
     "upgrade": "node plugins/manifest/upgrade-cli.ts"
   },