@timqi/pier 0.0.9 → 0.0.15

package/dist/web/server.js

@@ -14,8 +14,11 @@ import { Router } from "../core/router.js";
 import { registerExplorerRoutes } from "./explorer.js";
 import { guarded, registerFileRoutes } from "./files.js";
 import { isThinkingLevel } from "../core/types.js";
+import { SESSION_TITLE_MAX } from "../limits.js";
 import { saveInbound } from "../core/inbox.js";
 import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
+import { RepoIndex } from "./repos.js";
+import {} from "./session-state.js";
 import { registerInstanceRoutes } from "./instance.js";
 import { registerProviderRoutes } from "./providers.js";
 const log = logger("web");
@@ -37,7 +40,7 @@ export const withTabPrefix = (html, prefix) => prefix
 const HEARTBEAT_MS = 15_000;
 // Canonical base64 only: Buffer.from(.., "base64") happily "decodes" garbage.
 const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
-export function createServer({ factory, router, hub, sessions: state, config, providers, settings, extensions, secrets, onUnlocked, reload, updates, updater, backgroundRuns, channelOf, }) {
+export function createServer({ factory, router, hub, sessions: state, config, providers, settings, catalog, names, onToolsChanged, validateCustomTools, secrets, onUnlocked, reload, updates, updater, backgroundRuns, channelOf, }) {
     const app = new Hono();
     // A finished turn marks its session unread until some client reports it was
     // seen (session selected + tab visible → POST read below). Server-side so
@@ -57,6 +60,8 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         state.setUnread(e.sessionId, true);
         hub.emitWorkspace({ type: "sessions-changed" });
     });
+    // Repository identity per project directory, refreshed off the request path.
+    const repos = new RepoIndex(() => hub.emitWorkspace({ type: "sessions-changed" }));
     /** Background runs this session launched that are still in flight. */
     const activeRuns = (id) => backgroundRuns?.(id).filter((r) => r.state === "queued" || r.state === "running").length ?? 0;
     /** The web channel's session for `id` — every session route resolves here. */
@@ -65,39 +70,80 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     // only once the first assistant message lands. Merged into the list below
     // so every client sees a new session immediately; dropped once Pi lists it.
     const nascent = new Map();
-    // listAll parses every transcript. Concurrent consumers share that work,
-    // but the result is not retained: an explicit All-sessions open stays fresh.
+    /** `ensure`, plus ghost cleanup. A session created and never messaged does
+     *  not survive a restart or an eviction (Pi persisted nothing), but while
+     *  this process lives it is in `nascent` and therefore in the rail — left
+     *  alone, clicking it 404s forever. The load path is where a ghost is
+     *  discovered, so it is where the entry and its pin are dropped and every
+     *  rail told; the 404 then says what happened instead of looking like a
+     *  crash (§5b). */
+    const ensureLoadable = async (id) => {
+        try {
+            return await ensure(id);
+        }
+        catch (err) {
+            if (String(err).includes("unknown session")) {
+                nascent.delete(id);
+                state.forget(id);
+                hub.emitWorkspace({ type: "sessions-changed" });
+                throw new Error(`session ${id} no longer exists — it never got a first reply, so nothing was persisted; its rail entry was removed`);
+            }
+            throw err;
+        }
+    };
+    // A listing stats every session file and parses whatever grew — milliseconds
+    // warm, one scan cold. Concurrent consumers share it, whatever the factory
+    // behind the seam retains of its own; nothing here is cached past the last
+    // of them.
     let listing;
-    let projectBackfillNeeded = state.needsProjectBackfill();
-    const listSessions = () => listing ??= factory.list()
-        .then((rows) => {
-        state.remember(rows);
-        return rows;
-    })
-        .finally(() => {
+    const listSessions = () => listing ??= factory.list().finally(() => {
         listing = undefined;
     });
-    // `order` is where the workbench was arranged to put this row, not a fact
-    // about the Pi session — it rides along so one Projects read is enough.
-    const present = (s, pinned, unread, order = {}) => ({
-        ...s,
-        ...order,
-        state: router.stateOf(s.id) ?? "idle",
-        pinned,
-        unread,
-        channel: channelOf?.(s.id) ?? "web",
-        activeRuns: activeRuns(s.id),
-    });
+    /** Every session a surface may show: what Pi has written, plus the ones
+     *  created here that it has not persisted yet. */
+    const allSessions = async () => {
+        const sessions = await listSessions();
+        for (const s of sessions)
+            nascent.delete(s.id);
+        // A session created but never prompted would otherwise be listed forever.
+        for (const [id, n] of nascent)
+            if (Date.now() - n.createdAt > 86_400_000)
+                nascent.delete(id);
+        return [
+            ...[...nascent].map(([id, n]) => ({ id, ...n })),
+            ...sessions,
+        ];
+    };
+    // One session as every list renders it: the summary, what the workbench
+    // decided about it, and what is true of it right now.
+    // The listing's `modified` is dropped rather than forwarded: it dates a
+    // transcript, and no surface renders it.
+    const present = ({ modified: _drop, ...s }, own) => {
+        return {
+            ...s,
+            ...(own?.sort === undefined ? {} : { sort: own.sort }),
+            ...(own?.projectSort === undefined ? {} : { projectSort: own.projectSort }),
+            // Which repository the directory belongs to, on every list and not only
+            // on the rail's: All sessions replaces the client's whole list, so a row
+            // without it there un-groups the worktrees the rail had just grouped.
+            // Whatever is known now — the probe is never waited on, and its answer
+            // arrives as a `sessions-changed`.
+            ...repos.get(s.cwd),
+            state: router.stateOf(s.id) ?? "idle",
+            listed: own?.pinned ?? false,
+            unread: own?.unread ?? false,
+            channel: channelOf?.(s.id) ?? "web",
+            activeRuns: activeRuns(s.id),
+        };
+    };
+    // The rail: the same rows as the full list, minus everything Projects is not
+    // showing. One source, one shape — the rail used to read a second copy of
+    // the summaries out of SQLite, which is what had to be kept in step.
     app.get("/api/projects", async (c) => {
-        // Existing databases have pin booleans but no summaries. Pay one legacy
-        // scan, fill those rows, then every later Projects read is SQLite-only.
-        if (projectBackfillNeeded) {
-            await listSessions();
-            // Do not retry on every request, and do not clear a pin whose transcript
-            // happened to be unreadable. A later explicit full listing can repair it.
-            projectBackfillNeeded = false;
-        }
-        return c.json(state.projects().map(({ sort, projectSort, ...s }) => present(s, true, s.unread, { sort, projectSort })));
+        const flags = state.flags();
+        return c.json((await allSessions())
+            .map((s) => present(s, flags.get(s.id)))
+            .filter((row) => row.listed));
     });
     // One drag, one write of the list that changed: the projects, or one
     // project's sessions. Whole lists rather than a move — the client has just
@@ -120,21 +166,8 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         return c.json({ ok: true });
     });
     app.get("/api/sessions", async (c) => {
-        const sessions = await listSessions();
-        for (const s of sessions)
-            nascent.delete(s.id);
-        // A session created but never prompted would otherwise be listed forever.
-        for (const [id, n] of nascent)
-            if (Date.now() - n.createdAt > 86_400_000)
-                nascent.delete(id);
         const flags = state.flags();
-        return c.json([...[...nascent].map(([id, n]) => ({ id, ...n })), ...sessions].map((s) => {
-            const row = flags.get(s.id);
-            return present(s, row?.pinned ?? false, row?.unread ?? false, {
-                sort: row?.sort,
-                projectSort: row?.projectSort,
-            });
-        }));
+        return c.json((await allSessions()).map((s) => present(s, flags.get(s.id))));
     });
     app.post("/api/sessions", async (c) => {
         const body = await c.req.json().catch(() => ({}));
@@ -146,7 +179,7 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         nascent.set(session.id, { cwd: body.cwd, createdAt });
         router.attach({ channelId: "web", conversationId: session.id }, session);
         // Created here = part of the workspace; pinning is what Projects lists.
-        state.pin({ id: session.id, cwd: body.cwd, createdAt }, true);
+        state.pin(session.id, body.cwd, true);
         hub.emitWorkspace({ type: "sessions-changed" });
         return c.json({ id: session.id }, 201);
     });
@@ -162,20 +195,17 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     });
     app.post("/api/sessions/:id/pin", async (c) => {
         const body = await c.req.json().catch(() => null);
-        if (typeof body?.pinned !== "boolean" ||
-            typeof body.cwd !== "string" || !body.cwd ||
-            typeof body.createdAt !== "number" || !Number.isFinite(body.createdAt) ||
-            (body.title !== undefined && typeof body.title !== "string")) {
-            return c.json({ error: "pinned and session summary required" }, 400);
-        }
-        // The summary came from this authenticated surface's own list. Persisting
-        // it here makes the next Projects read independent of Pi's transcript scan.
-        state.pin({
-            id: c.req.param("id"),
-            cwd: body.cwd,
-            createdAt: body.createdAt,
-            ...(body.title ? { title: body.title.slice(0, 80) } : {}),
-        }, body.pinned);
+        if (typeof body?.pinned !== "boolean")
+            return c.json({ error: "pinned required" }, 400);
+        const id = c.req.param("id");
+        // The directory comes from the listing, not from the client that clicked:
+        // it is the one fact this row keeps about the session, it is the key a
+        // project's manual place is stamped on, and the browser is not where a
+        // path should come from when the server already knows it.
+        const cwd = (await factory.find(id))?.cwd ?? nascent.get(id)?.cwd;
+        if (!cwd)
+            return c.json({ error: `session ${id} has no directory Pier can find` }, 404);
+        state.pin(id, cwd, body.pinned);
         hub.emitWorkspace({ type: "sessions-changed" });
         return c.json({ pinned: body.pinned });
     });
@@ -188,7 +218,7 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     // deltas from SSE — transcript, live state, pending queue, model.
     guarded(app, "GET", "/api/sessions/:id/history", 404, async (c) => {
         const id = c.req.param("id");
-        const session = await ensure(id);
+        const session = await ensureLoadable(id);
         return c.json({
             turns: (await session.history()).map(slim),
             lastSeq: hub.lastSeq(id),
@@ -283,11 +313,14 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         const { sessionId } = await router.dispatch({
             key: { channelId: "web", conversationId: id },
             senderId: "web",
+            // Named, not anonymous: a session reached from a group chat as well as
+            // from here attributes an unheaded message to whoever spoke last
+            // (core/identity.ts), which is the operator's own words in someone
+            // else's mouth.
+            sender: { id: "web", name: "operator" },
             text: body.text,
             mode,
         });
-        if (state.title(id, body.text))
-            hub.emitWorkspace({ type: "sessions-changed" });
         return c.json({ sessionId }, 202);
     });
     // Edit a user turn: rewind the transcript to just before it, then re-send
@@ -308,9 +341,13 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         if (session.state === "streaming")
             return c.json({ error: "busy — stop the turn first" }, 409);
         await session.rewindToUserTurn(index);
+        // The rewind took the turns after this one out of the context, headers and
+        // all; what the model was told about who is speaking went with them.
+        router.forgetSender(id);
         await router.dispatch({
             key: { channelId: "web", conversationId: id },
             senderId: "web",
+            sender: { id: "web", name: "operator" },
             text: body.text,
             mode: "auto",
         });
@@ -336,6 +373,9 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
             return c.json({ error: "queue is empty" }, 409);
         if (mode === "restart")
             await router.abort(id); // resolves once idle
+        // No sender here, unlike the other dispatches: the queued texts were
+        // headed when they were first dispatched — and in a shared session they
+        // are other speakers' words, which an operator header would claim.
         await router.dispatch({
             key: { channelId: "web", conversationId: id },
             senderId: "web",
@@ -346,10 +386,48 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     });
     // Recall: drop all pending queued messages and hand them back (composer restore).
     guarded(app, "POST", "/api/sessions/:id/queue/recall", 404, async (c) => {
-        const session = await ensure(c.req.param("id"));
+        const id = c.req.param("id");
+        const session = await ensure(id);
         const { steering, followUp } = await session.clearQueue();
+        // Those messages carried the header that told the session who is speaking,
+        // and they are going back to the composer instead of to the model.
+        if (steering.length || followUp.length)
+            router.forgetSender(id);
         return c.json({ messages: [...steering, ...followUp] });
     });
+    // Shrink the context on demand: Pi summarizes the older transcript away and
+    // the session continues from the summary. Refused while streaming, like the
+    // edit route above and for the same reason — Pi's own compaction aborts a
+    // running turn to do it, and losing a turn is not what the button offered.
+    // The result is not in this response: it arrives on the session's stream as
+    // `context-compacted` (agent/events.ts), which is also the only place the
+    // automatic compaction can be seen.
+    guarded(app, "POST", "/api/sessions/:id/compact", 404, async (c) => {
+        const session = await ensure(c.req.param("id"));
+        if (session.state === "streaming")
+            return c.json({ error: "busy — stop the turn first" }, 409);
+        // The check above is a courtesy, not the lock: two clicks pass it on the
+        // same tick, so the seam refuses the second one (agent/pi.ts) and its
+        // refusal keeps the status this route already uses for "not now" — a 404
+        // from `guarded` would have read as "no such session".
+        return await session.compact().then(() => c.json({ ok: true }, 202), (err) => c.json({ error: String(err) }, 409));
+    });
+    // A name, so a title is what you called it instead of the first 80
+    // characters you happened to type. Not refused while streaming: a rename has
+    // nothing to do with the turn running, and the transcript takes an append.
+    guarded(app, "POST", "/api/sessions/:id/rename", 404, async (c) => {
+        const body = await c.req.json().catch(() => null);
+        if (typeof body?.name !== "string")
+            return c.json({ error: "name required" }, 400);
+        const id = c.req.param("id");
+        await (await ensure(id)).rename(body.name.trim().slice(0, SESSION_TITLE_MAX));
+        // Nothing to write and nothing to report: the name went into the
+        // transcript, which is what every list reads. The event is how the
+        // surfaces learn to re-read it, and the seam dropped its retained scan on
+        // the way out so the re-read sees the new name.
+        hub.emitWorkspace({ type: "sessions-changed" });
+        return c.json({ ok: true });
+    });
     app.post("/api/sessions/:id/abort", async (c) => {
         const id = c.req.param("id");
         await router.abort(id);
@@ -423,7 +501,10 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         updates,
         updater,
         secrets,
-        extensions,
+        catalog,
+        names,
+        onToolsChanged,
+        validateCustomTools,
         onUnlocked,
         onSettingsChanged: () => recycle("instance settings"),
     });

package/dist/web/session-state.js

@@ -1,6 +1,20 @@
-// Workbench organization state: which sessions show up under Projects, the
-// summaries needed to render them without scanning Pi, and which have a
-// finished turn no client has looked at yet.
+// What the workbench decided about a session, and nothing a transcript already
+// knows. Ownership of a row in Projects (`pinned`), a finished turn nobody has
+// looked at (`unread`), and the two places a hand put it in (`sort`,
+// `project_sort`).
+//
+// It used to mirror the summary too — cwd, title, created_at, last_active —
+// because listing sessions meant parsing every transcript on disk (~237ms) and
+// the rail could not pay that on every read. agent/listing.ts made a listing
+// cheap, so the mirror bought nothing and cost two stores kept in step: a
+// backfill gate, a repair pass on every full listing, a touch at the end of
+// every turn, a title write on the first prompt, a second write on rename.
+// Deriving beats syncing; all of it is gone.
+//
+// `cwd` stayed, and is not a mirror: it is the key a project's manual place is
+// stamped on (`reorder`, and the sibling lookup in `pin`), and a session's
+// working directory is fixed when its transcript is created — an immutable key
+// needs no synchronising.
 //
 // One row per session rather than two JSON files: the unread flag is written at
 // the end of every turn, and rewriting a whole file on each of those writes
@@ -20,20 +34,20 @@ export class SessionStateStore {
         this.#db.prepare(`INSERT INTO session_state(session_id, unread) VALUES (?, ?)
        ON CONFLICT(session_id) DO UPDATE SET unread = excluded.unread`).run(sessionId, unread ? 1 : 0);
     }
-    /** Pin plus the summary Projects needs, atomically in one row. */
-    pin(summary, pinned) {
+    /** Projects takes the session, or gives it up. Membership lasts until a hand
+     *  ends it: nothing expires, so what is pinned is what the rail draws until
+     *  the ✓ on the row says otherwise. */
+    pin(sessionId, cwd, pinned) {
         // A new session joins a project that already has a place in the list.
         // Unranked it would sort on top — lifting the whole project with it, which
         // is the jump manual order exists to stop.
-        const sibling = this.#db.prepare("SELECT project_sort AS rank FROM session_state WHERE cwd = ? AND project_sort IS NOT NULL LIMIT 1").get(summary.cwd);
-        this.#db.prepare(`INSERT INTO session_state(session_id, pinned, cwd, title, created_at, project_sort)
-       VALUES (?, ?, ?, ?, ?, ?)
+        const sibling = this.#db.prepare("SELECT project_sort AS rank FROM session_state WHERE cwd = ? AND project_sort IS NOT NULL LIMIT 1").get(cwd);
+        this.#db.prepare(`INSERT INTO session_state(session_id, pinned, cwd, project_sort)
+       VALUES (?, ?, ?, ?)
        ON CONFLICT(session_id) DO UPDATE SET
          pinned = excluded.pinned,
          cwd = excluded.cwd,
-         title = COALESCE(excluded.title, session_state.title),
-         created_at = excluded.created_at,
-         project_sort = COALESCE(session_state.project_sort, excluded.project_sort)`).run(summary.id, pinned ? 1 : 0, summary.cwd, summary.title ?? null, summary.createdAt, sibling?.rank ?? null);
+         project_sort = COALESCE(session_state.project_sort, excluded.project_sort)`).run(sessionId, pinned ? 1 : 0, cwd, sibling?.rank ?? null);
     }
     /** One drag = one write of the whole list it reordered: index is the place.
      *  `sessions` are ids (a session's place inside its project), `projects` are
@@ -46,41 +60,12 @@ export class SessionStateStore {
             order.projects?.forEach((cwd, i) => byCwd.run(i, cwd));
         });
     }
-    /** Project rows only; unlike AgentFactory.list(), this never touches disk. */
-    projects() {
-        const rows = this.#db.prepare(`SELECT session_id AS id, cwd, title, created_at AS createdAt, unread,
-              sort, project_sort AS projectSort
-       FROM session_state
-       WHERE pinned = 1 AND cwd IS NOT NULL AND created_at IS NOT NULL
-       ORDER BY created_at DESC`).all();
-        return rows.map(({ title, unread, sort, projectSort, ...row }) => ({
-            ...row,
-            ...(title ? { title } : {}),
-            ...(sort === null ? {} : { sort }),
-            ...(projectSort === null ? {} : { projectSort }),
-            unread: unread === 1,
-        }));
-    }
-    /** What to call a session where there is room for one line — a push
-     *  notification's title. Falls back to the project directory, then to the
-     *  fact that it is a session at all: a notification with no title reads as a
-     *  browser bug rather than as an unnamed session. */
-    name(sessionId) {
-        const row = this.#db.prepare("SELECT title, cwd FROM session_state WHERE session_id = ?").get(sessionId);
-        return row?.title || row?.cwd?.split("/").filter(Boolean).at(-1) || "Pier session";
-    }
-    needsProjectBackfill() {
-        return this.#db.prepare("SELECT 1 FROM session_state WHERE pinned = 1 AND (cwd IS NULL OR created_at IS NULL) LIMIT 1").get() !== undefined;
-    }
-    /** A full listing is rare; use it to repair metadata for rows we already own. */
-    remember(summaries) {
-        const update = this.#db.prepare(`UPDATE session_state SET
-         cwd = ?, title = COALESCE(?, title), created_at = ?
-       WHERE session_id = ?`);
-        this.#tx(() => {
-            for (const s of summaries)
-                update.run(s.cwd, s.title ?? null, s.createdAt, s.id);
-        });
+    /** Drop a session's organization row entirely — pin, order, unread. For
+     *  ghosts: Pi persists a session only once its first assistant reply lands,
+     *  so a created-and-never-messaged one cannot be resumed, and its remembered
+     *  row would otherwise sit in the rail 404ing forever. */
+    forget(sessionId) {
+        this.#db.prepare("DELETE FROM session_state WHERE session_id = ?").run(sessionId);
     }
     /** All-or-nothing: a half-written order is a list nobody arranged. */
     #tx(run) {
@@ -94,6 +79,8 @@ export class SessionStateStore {
             throw err;
         }
     }
+    /** What this store knows about the sessions it knows anything about, for a
+     *  caller holding the listing. */
     flags() {
         const rows = this.#db.prepare(`SELECT session_id AS id, pinned, unread, sort, project_sort AS projectSort
        FROM session_state WHERE pinned = 1 OR unread = 1`).all();
@@ -104,9 +91,4 @@ export class SessionStateStore {
                 ...(r.projectSort === null ? {} : { projectSort: r.projectSort }),
             }]));
     }
-    /** The first prompt supplies the title of a newly-created pinned session. */
-    title(sessionId, text) {
-        const result = this.#db.prepare("UPDATE session_state SET title = ? WHERE session_id = ? AND pinned = 1 AND title IS NULL").run(text.trim().slice(0, 80), sessionId);
-        return result.changes > 0;
-    }
 }

package/dist/web/types.js

@@ -0,0 +1,5 @@
+// The shapes web's HTTP answers carry beyond the stores they come from — the
+// area's own wire vocabulary, and the one file in web/ the browser may import
+// type-only (docs/architecture.md, same rule as tasks/types.ts). Nothing here
+// runs: no imports, no values, so a page pays nothing for reading it.
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timqi/pier",
-  "version": "0.0.9",
+  "version": "0.0.15",
   "description": "A self-hosted workspace for coding agents: web workbench and IM channels in front of Pi sessions",
   "license": "AGPL-3.0-only",
   "repository": "github:timqi/pier",

package/skills/pier-boards/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pier-boards
-description: Publish a Board — a folder of static HTML Pier serves at a stable URL — to present a report, digest, dashboard or handover note to the user. Read before building any page-shaped deliverable, or before editing an existing board.
+description: Publish a Board — a folder of static HTML Pier serves at a stable URL. Read before building any page-shaped deliverable (report, digest, dashboard) or editing an existing board.
 ---
 
 # Building a Pier board
@@ -27,23 +27,33 @@ session may read or rewrite any board, and closing this one changes nothing.
 }
 ```
 
-Those four fields are the whole manifest.
+Those four fields are the whole manifest (publishing adds a fifth — below).
 
-- `slug`: `[a-z0-9][a-z0-9-]{0,63}`, and it is the URL — short and stable.
+- `slug`: `[a-z0-9][a-z0-9-]{0,63}`, and it is the URL — short and stable. Do
+  not add random characters of your own; publishing adds them (see below).
 - `description` is the Console list entry: write it for someone who has
   forgotten this conversation.
 - `sessions`: append your own id, never replace — other ids are provenance too.
 
 ## Publish, then hand over the link
 
-`"public": true` serves the board at `/p/<slug>/` **with no password**. Set it
-only if the user asked for a public or shareable board *in this request*;
-otherwise leave it `false` and say the board is private. Never publish personal
-data or anything the user has not seen.
+`"public": true` serves the board **with no password**. Set it only if the user
+asked for a public or shareable board *in this request*; otherwise leave it
+`false` and say the board is private. Never publish personal data or anything
+the user has not seen.
 
-Asked to make an existing board public? Flip `"public"` to `true` in
-`board.json` and reply with the `/p/<slug>/` link — that is the whole answer.
-No verification step, no narrating the edit, no restating what the page holds.
+The published address is `/p/<slug>-<token>/`, not `/p/<slug>/`, so a public
+board's URL cannot be guessed from its name. `token` is a fifth manifest field
+you write next to `"public": true` — eight hex characters from
+`openssl rand -hex 4`, never invented in your head, never reused between
+boards. Leave it out and Pier mints one on the first request, but then the link
+is only visible in the Console, so write it yourself and you can hand it over
+in the same message.
+
+Asked to make an existing board public? Set `"public": true` and a fresh
+`token` in `board.json`, then reply with the `/p/<slug>-<token>/` link — that is
+the whole answer. Already has a token? Keep it: the link may be out there. No
+verification step, no narrating the edit, no restating what the page holds.
 
 The message announcing the board carries **one bare URL** — paste the address
 itself, never `[title](url)`: link labels get mangled or truncated on some chat
@@ -54,10 +64,10 @@ surfaces, and the title is already on the page. No filesystem paths either —
 | The user asked for | Send |
 | --- | --- |
 | a board, nothing about sharing | `https://pier.example.com/boards/weekly-digest/` — behind the Pier password; Console → Boards makes it public |
-| a **public** board | `https://pier.example.com/p/weekly-digest/` — no password |
+| a **public** board | `https://pier.example.com/p/weekly-digest-3f9ac128/` — no password; the suffix is the manifest's `token`, copied verbatim |
 
 Never both: the pair invites pasting the password-free URL of a board that was
-never meant to leave the workspace, and `/p/<slug>/` 404s unless the manifest
+never meant to leave the workspace, and `/p/<slug>-<token>/` 404s unless the manifest
 says `"public": true`. No address configured? Give the path, say Console →
 Settings turns it into a link, and never guess a host.
 
@@ -74,7 +84,7 @@ build, no npm, no framework:
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Weekly digest — infra</title>
-<link rel="stylesheet" href="/boards/_assets/pier.css">
+<link rel="stylesheet" href="/p/_assets/pier.css">
 </head>
 <body>
 <div class="hero">

package/skills/pier-help/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pier-help
-description: How Pier itself works — durable sessions and what survives a restart, how messages and files reach you from Slack and Telegram, in-chat commands (/stop, /settings, /bind), interrupting a running turn, and what only the operator's Console can change. Read before explaining Pier's behavior or advising a user on how to use it.
+description: How Pier itself works — durable sessions, what survives a restart, how messages and files reach you from IM, in-chat commands, and what only the operator's Console can change. Read before explaining Pier's behavior or advising a user on it.
 ---
 
 # How Pier works

package/skills/pier-slack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pier-slack
-description: Read and write Slack through Pier's slack tool — a channel's history for a time range, one thread, posting into a thread, deleting a message Pier posted, and the Slack-specific syntax for mentions and links. Read before answering questions about Slack conversations or posting anything to a workspace.
+description: Read and write Slack through Pier's slack tool, including the Slack-specific syntax for mentions and links. Read before answering questions about Slack conversations or posting anything to a workspace.
 ---
 
 # Reading and writing Slack
@@ -97,6 +97,26 @@ Going top-level takes the explicit `"none"`: a channel's main flow is wider
 than a thread. A `thread_ts` is never inherited across a change of `channel`.
 The response carries `ts` and `threadTs` for replying under what you posted.
 
+## Editing
+
+```json
+{"operation":"edit","channel":"#ops","ts":"1717243800.000100",
+ "text":"**Deploy done** — 3 services, 1 rollback."}
+```
+
+`text` replaces the message outright; there is no partial edit. Read the
+message first if you are changing part of it.
+
+- Slack only lets Pier edit what **its own bot** posted — anyone else's message
+  answers `cant_update_message`, and the answer is to reply, not to retry.
+- `ts` is always explicit, as with `delete`, and means nothing outside the
+  channel it was read in.
+- The old text is gone — Slack keeps no version a reader can open, and may not
+  mark the message as edited at all. When the previous wording mattered to
+  people reading, say what changed rather than quietly rewriting history.
+- A long-running update — a status line, a running tally — is better as one
+  message edited in place than as a new message per change.
+
 ## Deleting
 
 ```json

package/skills/pier-tasks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pier-tasks
-description: Delegate work to Pier subagents with the task tool — one-shot delegation, core-joined parallel fan-out, chained steps, and mid-run control (steer/resume/contact). Read before delegating to a subagent, coordinating multiple agents, or running long background work.
+description: Delegate work to Pier subagents with the task tool — one-shot, parallel fan-out, chains, mid-run control. Read before delegating to a subagent, coordinating agents, or running long background work.
 ---
 
 # Orchestrating Pier tasks
@@ -38,7 +38,7 @@ schedule policy, where `manual` means on-demand — by a human or by you.
 - The child inherits your current model unless `launch.model` is set.
   Unknown models fail with the available list in the error. `launch` applies to
   `fresh` and `fork` only — a `reuse` session owns its own model and tools.
-- The child has the same tools you do; there is no capability knob to pick.
+- The child has the same tools you do.
 - Runs time out after 900s by default; set `timeoutSeconds` in the draft for
   longer jobs.