NEXT.md: handoff for the next LLM to continue

Current state (24 plugins/244 tests), the hard rules (public-api-only;
don't touch core git), the immediate next step (finish wave 7:
webhooks/micropub/webmention/backup), the per-plugin loop, the wave-8+
backlog, the seam ranking to keep current, the footguns, and the open
items for the human. Linked from README.

Author: melvincarvalho

NEXT.md

@@ -0,0 +1,132 @@
+# NEXT.md — handoff for the next LLM
+
+You are continuing an in-progress effort to build out **out-of-tree plugins
+for JavaScript Solid Server (JSS)** and, through them, discover what the
+#206 plugin api is missing. Read this first, then `AGENT.md` (how to build a
+plugin), `NOTES.md` (the findings/seams — the real deliverable), and
+`ISSUES.md` (the plugin-tagged backlog triaged).
+
+## Where things stand
+
+- **24 plugins, ~270 tests, all green** (`npm test`), all pushed to
+  `github.com/JavaScriptSolidServer/plugins` (branch `gh-pages`).
+- `compose.test.js` boots all 24 on **one** JSS from pure config; `serve.js`
+  is the runnable demo. Both must be updated when you add a plugin.
+- Built so far: 6 ports (relay, webrtc, terminal, tunnel, notifications,
+  pay) + 18 features (nip05, corsproxy, capability, webdav, sparql,
+  gitscratch, otp, carddav, mastodon, bluesky, caldav, webfinger,
+  activitypub, rss, matrix, search, didweb, s3).
+- Capability classes covered: realtime, WebDAV family, fediverse/social/chat
+  (5 shims), identity, data/query/search, object storage, proxy, dev, pay.
+
+## The hard rule (don't break it)
+
+1. A plugin's `plugin.js` imports **only** node builtins, this repo's deps
+   (`@noble/curves`, `ws`), and `javascript-solid-server/auth.js`. **Never
+   `javascript-solid-server/src/...`.** A wall you can't cross without an
+   internal *is a finding* — document it, approximate honestly, move on.
+2. **Do NOT modify the JavaScriptSolidServer core repo** (no commits,
+   branches, or PRs there). Everything goes in *this* repo. (The maintainer
+   set this explicitly. Two core PRs — #590 `api.mountApp`, #591
+   `/idp/refresh` — are already open and awaiting their call; leave them.)
+3. Core is at `~/remote/github.com/JavaScriptSolidServer/JavaScriptSolidServer`,
+   pinned to 0.0.215 on `gh-pages`. You may **read** it for reference; keep
+   it clean.
+
+## Immediate next step: finish Wave 7
+
+Four plugins were *planned but not yet built* — this is where to resume:
+
+| Plugin | What | Copy from |
+|---|---|---|
+| `webhooks/` | change-notification webhooks; **must poll** (no `api.events`) → the canonical 5th consumer of that seam, and a real integration primitive | notifications/ (fs.watch), rss/sparql (container walk) |
+| `micropub/` | IndieWeb Micropub server — POST creates a post in the pod | mastodon/ (auth + pod write via loopback) |
+| `webmention/` | IndieWeb Webmention receiver — store incoming mentions in the pod | activitypub/ inbox, capability/ |
+| `backup/` | pod container → `.tar.gz` download (data portability); hand-roll tar headers + `node:zlib` gzip (no deps) | webdav/rss (container walk) |
+
+Dispatch each as its own worker into its own directory (they don't conflict
+— separate subdirs, shared files touched only by you at integration time).
+Verify each with `node --test --test-concurrency=1 <name>/test.js`, then:
+
+## The per-plugin loop (do this for every plugin)
+
+1. Build `<name>/{plugin.js,test.js,README.md}` per `AGENT.md`. README must
+   have a `## Findings` section — the findings are the point.
+2. `node --test --test-concurrency=1 <name>/test.js` → green.
+3. `git add <name>/ && git commit && git push` (commit message: what it
+   does + its headline finding; **no AI-generated footer/trailer** — the
+   maintainer's global rule).
+4. After a wave lands, integrate: add entries to `compose.test.js` and
+   `serve.js` (give each an explicit `id`; add any fixed roots to their
+   `appPaths`), add a liveness probe to `compose.test.js`, run `npm test`,
+   update `README.md` (table + count), `ISSUES.md` (tally), `NOTES.md`
+   (fold in new findings, re-rank seams by consumer count), and `AGENT.md`
+   (copy-map + count). Commit + push the integration.
+
+## Wave 8+ backlog (unbuilt ideas, roughly by value)
+
+Still genuinely plugin-shaped and distinct:
+- **JMAP** email API over pod messages (HTTP/JSON, unlike stateful IMAP).
+- **oEmbed** provider for pod resources (link unfurling).
+- **feed ingest** — subscribe to external RSS/Atom, store items in the pod
+  (the inverse of `rss/`; uses a corsproxy-style fetch).
+- **healthz / Prometheus `/metrics`** and a **plugin status dashboard**
+  (ops; the dashboard is a nice meta-demo listing all loaded plugins).
+- **link-shortener**, **WebSub/PubSubHubbub** (needs `api.events`),
+  **SPARQL UPDATE** (extends `sparql/`), **CalDAV scheduling/free-busy**
+  (extends `caldav/`), **remoteStorage** (another bundled-feature port).
+- **Bluesky/Mastodon/Matrix Phase-2** (federation, `/sync` live push) —
+  these are blocked on `api.events` + `api.reservePath`; good once those
+  seams exist, otherwise document the wall.
+
+Prefer plugins that open a **new capability class** or add a **new
+independent consumer of an already-named seam** (that strengthens the
+finding). Avoid re-proving something already witnessed many times unless
+it sharpens the case.
+
+## The findings are the deliverable — keep them sharp
+
+`NOTES.md` ranks candidate seams by how many independent plugins demanded
+each. Current top four (keep this current as you add consumers):
+
+1. **`api.authorize(request, path, mode)`** — 3 consumers; the top
+   *blocking* seam (authority the requester doesn't drive).
+2. **`api.events.onResourceChange`** — 4 consumers; matrix `/sync` needs
+   live push. Every "react to writes" plugin (webhooks, WebSub, indexing)
+   will want it — webhooks/ (wave 7) makes it 5.
+3. **`api.reservePath`** — every API-shim owns fixed roots outside its one
+   prefix and can't self-exempt; didweb needs a *parameterized* form.
+4. **`api.serverInfo`** — broadest (~10 plugins hand-roll their origin).
+
+Plus: the unconsumed-body-**stream** primitive (#583), `api.mcp.registerTool`
+(blocks the MCP-tool issues #495/#496/#500/#501), can't-set-server-options,
+and response-header hooks. `#564` (the core/plugin line) is answered
+empirically in NOTES: **route-owning → plugin, pipeline-modifying → core**.
+
+## Meta-work worth doing (beyond more plugins)
+
+- **A summary write-up** the maintainer can act on: "the plugin api reaches
+  N of ~40 tagged issues; here are the M seams to add next, ranked, each
+  with consumers." Half of this exists in `ISSUES.md`/`NOTES.md` already.
+- **Filing the seams as upstream issues** — but only if the maintainer asks
+  (core-repo interaction is currently off; see the hard rule). Draft them
+  here first if so.
+
+## Footguns (every multi-boot test suite rediscovered these)
+
+- Module-global `DATA_ROOT`: a second `createServer` in one process (even a
+  failing one) poisons the first — order validation-failure tests *before*
+  the long-lived boot.
+- Ambient `~/.gitconfig` for git-shelling plugins: spawn with
+  `GIT_CONFIG_NOSYSTEM=1`, no `HOME`.
+- Generic-basename id: `<name>/plugin.js` all reduce to `plugin` — always
+  pass an explicit `id` in compose/serve entries.
+- Dotted prefixes (`/.foo`) fail the WS upgrade — use plain prefixes for
+  anything with a socket. (`/.well-known/*` HTTP works, by core's blanket
+  exemption — but that's the reserved-path finding, not a guarantee.)
+
+## Open items for the human (don't act without a nudge)
+
+- The repo exists and is public; keep pushing to it.
+- Core PRs #590 / #591 are unmerged — the maintainer's call.
+- Whether to ever file the seam issues upstream — ask first.

README.md

@@ -30,8 +30,10 @@ applied to JSS's own feature set.
 
 **[AGENT.md](./AGENT.md)** is the comprehensive guide for adding plugins —
 the api, the five reusable patterns, the gaps and their workarounds, a
-copy-this-plugin map, and the footguns. Read it, then `NOTES.md` (findings)
-and `ISSUES.md` (backlog).
+copy-this-plugin map, and the footguns. **[NEXT.md](./NEXT.md)** is the
+handoff for whoever (LLM or human) continues the work: current state, the
+next wave, the per-plugin loop, and the backlog. Read those, then `NOTES.md`
+(findings) and `ISSUES.md` (backlog triage).
 
 ## The rule