Make Deckle the knowledge base for an agent, and take the assistant out (3.0.0)

[authorTom]

A change of direction. Deckle stops being a note app with an AI assistant built in and becomes the place an agent's work lives — Hermes, or anything else that speaks MCP or HTTP. The agent does the thinking; Deckle stores what it produces, shows it, searches it, and keeps a record of what it did. Deckle itself calls no model and holds no AI keys.

Two commits: the work, then Cut 3.0.0 (package.json, lockfile, changelog), as for 2.0.0.

Before deploying

This is a major (3.0.0): an upgrade needs people to do something.

• The AI assistant is gone, with /api/assistant-settings. Libraries are untouched; .deckle/memory/ and .deckle/runs/ stay until someone deletes them.
• An old provider key may still be on the volume. Password-protected server libraries kept it in .deckle-state/assistant.json. Deckle still refuses to serve that folder, but the README and changelog tell people to delete the file and revoke the key.
• :latest crosses into 3.0 on the next pull. The README says so, and points anyone who wants the assistant at :2.
• API: the folder tree now includes files, as kind: "asset" nodes. Clients that assumed only folders and notes need to skip them. GET /notes still lists notes only.
• DELETE /folders/{path} bins files instead of erasing them.

Added

• Files beside notes. Any file sits in the tree and opens in a tab:
  • Images, PDF, audio and video preview in the browser's own viewers.
  • Word, every sheet of a workbook, PowerPoint, CSV, JSON and text render in the app.
  • Moves, renames, the bin and restore are byte-for-byte. On the server library they're a rename (new POST /api/library/move), not a download and re-upload.
• MCP server at /api/v1/mcp, behind the API's tokens. Streamable HTTP, stateless, JSON responses, with an Origin check.
  • Read tools: search, read, list, list_projects, recent_activity.
  • Write tools, for read-write tokens only: write_note, save_file, create_project, update_project, log_progress, move, delete.
• /api/v1/files (raw PUT/GET/DELETE and a listing) and /api/v1/activity. The OpenAPI document is updated.
• Projects. Each folder in Projects/ has an Overview.md (front matter: status, summary, tags) and a Log.md. A Projects view lists them, filters by status and changes status in place. A pushed code project's README is never written to.
• Activity. .deckle/activity.jsonl records the token behind every API and MCP write.
  • An Activity feed, with unseen counts on the panel tab and the top bar.
  • Provenance in the file viewer ("hermes saved it 2h ago — 'final report'").
  • Live refresh: the app polls the log's stat every 15s while visible, and reloads when it moves.
• Search inside documents. Word, Excel, PowerPoint, OpenDocument, CSV, JSON and text, through a zlib-only ZIP reader, so the server still has no dependencies.
• integrations/hermes/:
  • A setup guide (token, mcp_servers config, skill install).
  • A Hermes skill.
  • deckle_push.py for large files and folders. It uses the Python standard library only, and never sends .env files, keys, .git or dependency caches.
• Imports take any file. Hidden files and node_modules-style caches stay out.
• DECKLE_MAX_FILE_MB (default 100) and DECKLE_PROJECTS_DIR (default Projects).

Fixed along the way

• Images were deleted from notes. The editor had no image node, so every ![alt](src) was dropped on the next save. That bug is in 2.0 today. Images now render, including library-relative ones.
• Front matter was mangled by editing a note. It's now kept out of the editor, shown as an editable properties strip, and put back on save. A note that merely opens with a horizontal rule is not mistaken for front matter.
• An agent's rewrite of the note being typed in used to be silently overwritten. Typing still wins, but the agent's version is snapshotted to history first. A test covers that the app's own saves never trigger it.
• "Download .md" now copies the file, front matter included.

Changed

• CSP: connect-src 'self'. The page no longer needs AI providers. blob: is allowed for frames, objects and media, so stored PDFs and media can preview. Previews are only minted for images, PDF, audio and video, typed by extension; HTML is shown as text.
• Side panel: Projects · Activity · Tasks · Bookmarks. Inactive tabs show their icon only until the panel is wide enough.
• Docs: README (new intro, Connecting an agent, Upgrading from 2.x, image tags for 3.x), PRODUCT.md, DESIGN.md (the pencil section is replaced by "An Agent's Work"), CHANGELOG, .env.example, compose.yaml.
• Screenshots: files, projects and activity are new. Editor, tasks, bookmarks and palette are retaken without the assistant.
• @types/node is declared directly; it used to arrive through the SDK.

Test plan

• npm test: 294 tests in 21 files. 54 AI-specific tests were removed. New coverage:
  • MCP over HTTP: initialize, notifications, batches, read-only tokens, origin, and a whole project workflow.
  • /files and /activity.
  • The binary-safe bin, replace and move.
  • Projects, extraction from real docx, xlsx, pptx and odt, and zip-bomb limits.
  • Browser previews and front matter.
  • The remote adapter moving files without re-uploading.
  • The agent-edit snapshot guard.
• npm run build; npm ci --dry-run confirms the lockfile is in sync.
• End to end in Chrome against a built server, with a library seeded over MCP and REST as Hermes would. Checked:
  • The tree with files, and xlsx, docx, PDF, PNG and CSV previews.
  • A note with front matter and an embedded library image. Editing it keeps both on disk, byte for byte.
  • Projects status changes, and the Activity feed.
  • Live refresh when an agent writes while the page is open.
  • Dark mode. No page errors.
• deckle_push.py against the running server: skips .env, keys, .git, node_modules and .deckleignore matches. The binary arrives byte-identical. --no-overwrite works, and a bad token exits non-zero.
• A live Hermes session. Not available here: the MCP endpoint was exercised with the calls Hermes's documented mcp_servers config makes, not with Hermes itself.
• Docker image and TZ inside the Alpine image. No Docker daemon was available locally.
• Safari, Firefox and phone layouts of the new views. Only desktop Chrome was checked.

Known and not addressed

• PDFs and images are searchable by name only. Reliable PDF text extraction needs a dependency the server deliberately doesn't have. The Hermes skill asks the agent to describe important files in a note instead.
• No per-folder permissions: a read-write token reaches the whole library. Stated in the README's Security section.
• "Projects" now names two things: knowledge-base projects and task-planner projects. Renaming the task ones to "Lists" is a separate decision.
• Unused bottom-edge resize support remains in useResizable (only the assistant used it).

After merging

Tag v3.0.0 to publish 3.0.0, 3.0, 3 and :latest. Merging alone publishes :edge.

🤖 Generated with Claude Code