flatland-board 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.1.3 · 2026-09-27
+
+The first release on the npm registry, as `flatland-board`.
+
+**Install and remove cleanly**
+- `npm install -g flatland-board`, then `board install claude` or `board install codex`.
+- New: `board uninstall claude|codex` removes board's hooks and its command, and leaves every other setting as it was. Run it before `npm uninstall -g flatland-board`.
+- If board or its Node is removed anyway, its hooks stay silent instead of reporting an error on every prompt.
+- `board install` won't run from a temporary `npx` cache, whose hooks would break later. It also won't run as root.
+- New: `board --version`. `board doctor` now also checks each integration's hooks and command, and says when `ANTHROPIC_API_KEY` will bill the observer.
+
+**Steadier board**
+- A board opened in an earlier conversation exits after 15 idle minutes once it's detached and no page is open. Opening board again starts it.
+- Opening board after an upgrade replaces a board still running from the earlier version. The saved scene carries over.
+- A board left locked by a crash or a restart reopens.
+- A save that Windows briefly blocks is retried, and one failed save no longer stops later turns from being sketched.
+- On Windows, an observer that finishes just as board stops it is no longer reported as still running.
+- Hooks send conversation text only to their own running board.
+- The page also opens through a forwarded `localhost` port, as VS Code Remote and devcontainers provide.
+
+**Faster hooks**
+- Installed hooks run a small entry that loads nothing until you open board. Claude Code on Windows runs it with no shell.
+
+**Moving from a 0.1.1 or 0.1.2 tarball**
+- Those builds were named `@flatland/board`. Run `npm uninstall -g @flatland/board` first, because both packages provide the `board` command.
+- Then install `flatland-board` and run `board install` again for each harness. It replaces the earlier hooks.

package/LICENSE

@@ -0,0 +1,28 @@
+flatland board
+Copyright © 2026 Flatland Labs, Inc. All rights reserved.
+
+Flatland Labs, Inc. grants you a free, non-exclusive, non-transferable licence to
+install and use this software, unmodified, as published on the npm registry under
+the name "flatland-board", for any lawful purpose, including commercial work.
+
+You may not:
+
+- modify, adapt or translate the software, or create derivative works of it;
+- redistribute, sublicense, sell, rent or lease the software or any part of it;
+- extract the fonts bundled with the software, or use or redistribute them apart
+  from it;
+- remove or alter this notice or any other proprietary notice.
+
+Third-party components included in the software are licensed under their own
+terms, listed in THIRD-PARTY-NOTICES. Nothing in this licence limits your rights
+under those terms.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL FLATLAND LABS,
+INC. BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+This licence ends automatically if you breach it; you must then stop using and
+delete the software. Questions: info@flatlandfi.com

package/README.md

@@ -0,0 +1,110 @@
+# flatland board
+
+The agent whiteboard. Draw next to your agent, and it reads your drawing on its next turn. From Flatland Labs.
+
+flatland board is a whiteboard on your machine beside **one** Claude Code or Codex terminal conversation. After each completed turn, an observer sketches the salient idea. Circle an idea, cross out a path, or add a short phrase. Review the interpretation, then confirm it. The next prompt you submit in your terminal carries that direction, and your agent acknowledges it and adapts its reply.
+
+Ink is exploration. Only **Confirm direction** queues a correction. Approvals for your agent's actions stay with your terminal harness.
+
+## Requirements
+
+- **Node 22.18 or later.** The native Claude Code installer doesn't include Node; get it from nodejs.org.
+- **Claude Code**, current and logged in. The observer runs through it, even when the conversation you steer is in Codex.
+- **Codex CLI**, current, if you steer Codex conversations.
+- Windows, macOS or Linux.
+
+## Install
+
+```sh
+npm install -g flatland-board
+board install claude       # choose your harness; install both if you use both
+board install codex
+board doctor
+```
+
+Then start your agent normally, in a new session, so it loads board's hooks. Codex asks you to review and trust board's four hooks once, through `/hooks`. Setup never grants that trust itself, and it never changes your agent's tool approvals.
+
+On Windows, if PowerShell blocks npm's script shim, use `npm.cmd install -g flatland-board` and `board.cmd`.
+
+`board install` refuses to run from a temporary `npx` cache, because hooks baked from it would break when the cache is cleared. It also refuses to run as root: install as the user who runs your agent.
+
+## Open and detach
+
+| Terminal harness | Open within the existing conversation | Detach within the conversation |
+| --- | --- | --- |
+| Claude Code | `/board` | `/board off` |
+| Codex | `$board` or `/skills` → board | `$board off` |
+
+Codex rejects a bare `/board`; its extension entry is a skill, so type `$board` or choose board through `/skills`. These commands attach to the exact current conversation. They never launch, fork or replace your agent.
+
+Opening prints a private link and opens your browser when a desktop is available. Your agent gives a short visible recap of the conversation so far, which seeds the first sketch. If Codex asks to run the board command outside its sandbox, approve it: board starts a small local server that keeps running after the command returns.
+
+Detach with **Detach · stop observing** in the board's session menu, with `/board off` or `$board off`, or with `board off` in any terminal. Your conversation continues either way. Closing the browser tab doesn't detach. Open board again from the same conversation to bring back its ink, placements, sources and correction history. Only one conversation per installation can be attached at a time.
+
+## The surface
+
+- **V**: select. Click a mark, Shift-click to add or remove, or drag a freeform lasso. Drag selected marks to move them; a moved sketch stays where you put it.
+- **P**: pen, for circles and strikes. New ink stays selected, so a circle and a strike can be sent together.
+- **E**: erase. **T**: place a short typed thought. **H**, the middle mouse button, or Space-drag: pan.
+- Trackpad or wheel pans; Ctrl/⌘-wheel zooms. The controls at the bottom right zoom or fit the board.
+- **Send correction** opens a short, editable interpretation. **Cancel** leaves the ink untouched. **Confirm direction** queues it for the next prompt you submit, even while the current turn is still running.
+- Select a sketched phrase to open the turn it came from. The menu at the top right exports the board as an image and your confirmed direction as text. Everything saves automatically.
+
+Circles and near-straight strikes over phrases are read geometrically. Freehand writing, or ink that touches more than one idea, asks you what you mean. board doesn't read handwriting, and it never sends an image of the board to a model.
+
+## What board sees, sends and keeps
+
+- **Sees**: from the moment you open it, only the prompts you submit and your agent's final visible replies. Never transcripts, tool output or reasoning. Hooks installed for other conversations stay idle and store nothing.
+- **Sends**: after each completed turn, that turn's visible text (up to 32,000 characters from each side) and the short labels already on the board go to Claude Haiku through your own Claude Code. It runs unmodified with its existing login, or with `ANTHROPIC_API_KEY` when that's set, since Claude Code's `-p` mode always prefers the key; `board doctor` says which. Each sketch is capped at $0.12 of API-equivalent cost. With a subscription, your plan's usage and limits apply.
+- **Keeps**: saved boards, including those visible turns, in `~/.local/share/flatland-board` on your machine, with no expiry. Delete that folder to remove them. `BOARD_HOME` chooses another folder at install time.
+- Board's own server listens only on `127.0.0.1`, behind private tokens. Nothing is sent to Flatland Labs.
+
+## How direction reaches your agent
+
+A confirmed correction belongs to the exact conversation it was confirmed in. It's saved before your next prompt is sent, delivered once as context with that prompt, and your agent is asked to acknowledge it with a short `board <receipt>` line in its reply. Only that receipt marks it **delivered**.
+
+The session menu shows each correction as **queued**, **awaiting agent receipt**, **delivered** or **failed · retained in queue**. A queued correction can be cancelled, and a failed one dismissed. If a reply is lost, a turn is interrupted or no receipt comes back, board keeps the correction and doesn't send it again on later prompts, so direction is never repeated by accident. To try again, select the ink and confirm a new correction. A receipt shows your agent acknowledged the direction; it can't guarantee what the agent does next. board never approves tools or actions.
+
+## Upgrade
+
+```sh
+npm install -g flatland-board@latest
+board install claude       # again for each harness, to refresh its command and hooks
+```
+
+A board still running from the earlier version is replaced the next time you open board. Your saved ink carries over.
+
+If you installed a 0.1.1 or 0.1.2 tarball, it was named `@flatland/board`: run `npm uninstall -g @flatland/board` first, because both provide the `board` command.
+
+## Uninstall
+
+```sh
+board uninstall claude     # and/or codex: removes board's hooks and command, and nothing else
+npm uninstall -g flatland-board
+```
+
+Running sessions keep the hooks they loaded until they restart. Your saved boards stay in `~/.local/share/flatland-board` until you delete that folder. If you removed the package first, the hooks it left behind do nothing; reinstall and run `board uninstall` to clear them.
+
+## Troubleshooting
+
+- **The board stays on "connecting".** Your session started before board's hooks were installed, or Codex hasn't trusted them yet. Start a new session, and in Codex review the hooks with `/hooks`.
+- **"Board is attached to another conversation."** Detach that board from its session menu, or run `board off` in a terminal, then open board again.
+- **npm reports that `board` already exists.** Another package provides a `board` command. Uninstall it, or remove the earlier `@flatland/board`.
+- **Over SSH.** Forward the printed port from your own computer (`ssh -L PORT:127.0.0.1:PORT host`) and open the printed link there. VS Code Remote and devcontainers forward it for you; the forwarded `localhost` link works too.
+- **Something else.** `board doctor` checks Node, both CLIs, the observer's login, each integration's hooks and command, and your saved boards.
+
+If an observer can't be stopped, board pauses capture and offers **Retry stopping observer** in the session menu. Reopening the same board keeps this state, and no other conversation can start an observer until it's resolved. If Windows reports a possibly partial stop, or the board restarted before shutdown was confirmed, end the named observer and its child processes in your process manager (or restart your computer), then choose **Confirm observer stopped**. Your ink stays saved throughout.
+
+## Tested with
+
+- **Linux**: live, in both terminals: Claude Code 2.1.283 and Codex 0.156.1.
+- **Windows 11**: live, in both terminals: Claude Code 2.1.283 and Codex 0.157.1.
+- **macOS**: automated tests of the installed package only.
+
+Current releases of both CLIs are required, since board relies on their hook and skill formats.
+
+## Support and licence
+
+Write to info@flatlandfi.com.
+
+flatland board is free to use under its licence, in `LICENSE`. Third-party components and their licences are listed in `THIRD-PARTY-NOTICES`.

package/THIRD-PARTY-NOTICES

@@ -0,0 +1,77 @@
+flatland board includes or installs the following third-party components. Each is
+licensed under its own terms, reproduced or referenced below.
+
+Fonts bundled in dist/web
+-------------------------
+
+Atlas Typewriter (Regular and Medium)
+  Licensed to Flatland Labs, Inc. by its foundry for use in this software. The font
+  is not sublicensed: it may not be extracted, used apart from flatland board, or
+  redistributed.
+
+Instrument Sans 5.3.0 (@fontsource/instrument-sans)
+  Copyright 2022 The Instrument Sans Project Authors
+  (https://github.com/Instrument/instrument-sans)
+  SIL Open Font License, Version 1.1. The full licence ships in
+  dist/web/licenses/instrument-sans.txt.
+
+Noto Sans 5.3.0 (@fontsource/noto-sans)
+  Copyright 2022 The Noto Project Authors
+  (https://github.com/notofonts/latin-greek-cyrillic)
+  SIL Open Font License, Version 1.1. The full licence ships in
+  dist/web/licenses/noto-sans.txt.
+
+Code bundled in dist/web
+------------------------
+
+perfect-freehand 1.2.3
+  Copyright (c) 2021 Stephen Ruiz Ltd
+  MIT License (text below)
+
+Runtime dependencies installed by npm
+-------------------------------------
+
+Each keeps its own licence file in its package folder.
+
+zod 4.6.5                 Copyright (c) 2025 Colin McDonnell            MIT License
+cross-spawn 7.0.6         Copyright (c) 2018 Made With MOXY Lda         MIT License
+path-key 3.1.1            Copyright (c) Sindre Sorhus                   MIT License
+shebang-command 2.0.0     Copyright (c) Kevin Mårtensson                MIT License
+shebang-regex 3.0.0       Copyright (c) Sindre Sorhus                   MIT License
+which 2.0.2               Copyright (c) Isaac Z. Schlueter and Contributors  ISC License
+isexe 2.0.0               Copyright (c) Isaac Z. Schlueter and Contributors  ISC License
+
+MIT License
+-----------
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in the
+Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+ISC License
+-----------
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.