forma-diagrams 0.5.2

package/docs/self-hosting.md

@@ -0,0 +1,167 @@
+# Host Forma for your organization
+
+Hosted Forma supports Google sign-in and a private server-backed diagram library for each admitted user. Your organization operates the server, disk, domain, Google OAuth client, and backups. No Forma-operated service or external database is required. Local `forma serve` and static deployments still work without accounts.
+
+This release is **single-instance**, with private libraries rather than shared team folders. Do not run multiple replicas against the same data directory.
+
+## Configure Google
+
+Create a **Web application** OAuth client in your organization's Google Cloud project. Configure its consent screen and authorized users according to your organization's Google policy. Set the exact authorized redirect URI:
+
+```
+https://diagrams.example.com/auth/callback
+```
+
+Use the same origin for `FORMA_PUBLIC_URL`. Request only OpenID, email, and profile; Forma does not need Drive access. Use an Internal consent audience when suitable for your Workspace organization, or explicitly manage your External/test audience. Follow [Google's setup and OpenID Connect documentation](https://developers.google.com/identity/openid-connect/openid-connect).
+
+Store the client secret only on the host, never in a diagram, frontend build variable, public repository, or agent prompt. The server requires an allowlist even if the Google consent audience is restricted. Workspace domains use Google's `hd` claim, not email suffix matching.
+
+## Docker Compose with HTTPS
+
+Requires Docker Compose, a public domain pointing to your host, and inbound ports 80 and 443 available for Caddy. From a checkout:
+
+```sh
+cp deploy/.env.example deploy/.env
+```
+
+Edit `deploy/.env` with the public URL, real client ID/secret, and allowed Workspace domains and/or individual Google emails. The example values are placeholders. Then:
+
+```sh
+docker compose --env-file deploy/.env -f deploy/compose.yml up -d --build
+```
+
+Caddy terminates HTTPS and proxies to the unprivileged Forma container. Only Caddy publishes network ports. Persistent named volumes hold diagrams and TLS state. Do not run `down --volumes` unless you intentionally want to delete that data. See [Caddy reverse-proxy documentation](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy) and [Compose environment-file documentation](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/).
+
+Visit the public URL, sign in with an allowed Google account, and save a diagram in Library. Confirm that another allowed account has an independent library. Verify a disallowed account cannot sign in before inviting users.
+
+## Run with Node instead
+
+Build a source checkout with `npm ci && npm run build`, or install a release package. Configure environment variables through your service manager or a private environment file. For example, from a checkout using Node's environment-file support:
+
+```sh
+node --env-file=/etc/forma/forma.env packages/cli/bin.mjs host
+```
+
+A release installation exposes the same command as `forma host` when the environment is already loaded. A process supervisor should keep it running. Terminate TLS with your existing reverse proxy and preserve the original public `Host` header. Keep the upstream private. Do not expose the unauthenticated `forma serve` command.
+
+| Variable                     | Meaning / default                                                                       |
+| ---------------------------- | --------------------------------------------------------------------------------------- |
+| `FORMA_PUBLIC_URL`           | Required canonical HTTPS origin, without a path, such as `https://diagrams.example.com` |
+| `FORMA_GOOGLE_CLIENT_ID`     | Required Google Web client ID                                                           |
+| `FORMA_GOOGLE_CLIENT_SECRET` | Required server-only client secret                                                      |
+| `FORMA_DATA_DIR`             | Required durable directory; Compose sets `/data`                                        |
+| `FORMA_ALLOWED_EMAILS`       | Comma-separated explicit Google emails                                                  |
+| `FORMA_ALLOWED_DOMAINS`      | Comma-separated Google Workspace domains; at least one allowlist must be nonempty       |
+| `FORMA_BIND_HOST`            | `127.0.0.1`; Compose sets `0.0.0.0` on its private network                              |
+| `FORMA_PORT`                 | `4242`                                                                                  |
+| `FORMA_USER_BYTES`           | `100000000` bytes per user                                                              |
+| `FORMA_USER_FILES`           | `1000` diagrams per user, maximum 1000                                                  |
+| `FORMA_MAX_USERS`            | `500` user directories                                                                  |
+| `FORMA_ENABLE_MCP`           | `true` enables the optional Streamable HTTP MCP endpoint at `/mcp`; default is off      |
+
+HTTP is allowed only for `localhost` or `127.0.0.1` development origins and binds to loopback. Google must have the matching loopback callback URI registered. Production uses HTTPS Secure cookies. Forma does not infer its public URL from untrusted forwarded headers. `/healthz` is a public health endpoint, still subject to the canonical Host check.
+
+## Vercel (personal hosted editor)
+
+The static Vercel deployment can run the same Google sign-in and private library as `forma host`, using [Vercel Blob](https://vercel.com/docs/vercel-blob) instead of a local disk. Sessions are signed cookies, so they work across serverless invocations. This is a personal/small-team host, not a replacement for a dedicated VM when you need a locked data directory.
+
+1. Create a Google **Web application** OAuth client. Authorized JavaScript origin and redirect URI:
+
+```
+https://YOUR-DEPLOYMENT.vercel.app
+https://YOUR-DEPLOYMENT.vercel.app/auth/callback
+```
+
+2. Create a private Blob store and set environment variables on the Vercel project (Production and Preview):
+
+| Variable                     | Meaning                                                      |
+| ---------------------------- | ------------------------------------------------------------ |
+| `FORMA_HOSTED`               | `1` so the editor build includes the hosted sign-in shell    |
+| `FORMA_PUBLIC_URL`           | The stable `https://….vercel.app` origin (no path)           |
+| `FORMA_GOOGLE_CLIENT_ID`     | Google Web client ID                                         |
+| `FORMA_GOOGLE_CLIENT_SECRET` | Google client secret                                         |
+| `FORMA_ALLOWED_EMAILS`       | Your Google account, comma-separated if several              |
+| `FORMA_ALLOWED_DOMAINS`      | Optional Workspace `hd` values                               |
+| `FORMA_SESSION_SECRET`       | Long random string; changing it signs everyone out           |
+| `BLOB_READ_WRITE_TOKEN`      | Set automatically when a Blob store is linked to the project |
+
+3. Redeploy. Visit the production origin, sign in with an allowed Google account, and save a diagram in Library. Agent tokens from **Agent access** still work with `FORMA_REMOTE_URL` set to that origin.
+
+## Updating a hosted instance
+
+The application and the diagram store are separate. An update replaces Forma. It does not replace libraries, Blob objects, Docker volumes, or `FORMA_DATA_DIR` unless you delete those yourself.
+
+Check the latest GitHub [release](https://github.com/joeycast/forma/releases) and its notes before you move. Read the notes for env-var or OAuth-redirect changes. Google client secrets, allowlists, and session/Blob tokens stay on the host; they are not in the public repository.
+
+### Node (`forma host`)
+
+```sh
+npm install -g https://github.com/joeycast/forma/releases/download/v0.5.2/forma-diagrams-0.5.2.tgz
+```
+
+Restart the `forma host` process (or its supervisor). Leave `FORMA_DATA_DIR` pointed at the same disk. Verify `/healthz`, then sign in and open a known diagram.
+
+The npm registry package `forma-diagrams` is prepared but not published yet. Until it is, use the GitHub tarball above. Source checkouts update with `git fetch` and a checkout of the release tag, then `npm ci && npm run build`, then restart.
+
+### Docker Compose
+
+Keep the named volumes. Rebuild and recreate the app container from the tag you want:
+
+```sh
+git fetch
+git checkout v0.5.2
+docker compose --env-file deploy/.env -f deploy/compose.yml up -d --build
+```
+
+Do not pass `--volumes` to `docker compose down` unless you intend to delete diagrams and TLS state.
+
+### Vercel
+
+A Vercel project runs a specific deployment of this repository. Env vars and Blob data survive deploys.
+
+If Production is **not** connected to GitHub (CLI deploys only), update by deploying the tree you want:
+
+```sh
+git fetch
+git checkout v0.5.2
+vercel --prod --yes
+```
+
+If you connect GitHub, every push to the linked branch deploys that branch to the project. That is convenient and also means `main` commits go live on your login host. Prefer Production deploys from **release tags** when the project is your own workspace.
+
+After changing Vercel env vars (allowlist, OAuth, session secret), trigger a new deployment so the functions load the new values.
+
+npm does not update a Vercel site. Registry packages help CLI and `forma host` operators; Vercel still needs a git or CLI deploy of the app.
+
+## Daily use and agents
+
+After sign-in, Library opens to your private files. Create diagrams, organize them with relative paths such as `engineering/platform.forma.json`, and save explicitly. Reloading opens Library rather than restoring a private draft from browser storage. Unsaved hosted edits do not survive a page reload or sign-out; use Save or export a native copy first. Sign-out also closes authenticated views in other tabs.
+
+Use **Agent access** to issue a scoped, revocable token for a user’s own library. The agent never receives Google credentials or browser cookies. Set `FORMA_REMOTE_URL` to this origin and store the token in a private `chmod 600` file referenced by `FORMA_AGENT_TOKEN_FILE` (or `FORMA_AGENT_TOKEN` in the agent’s secret environment). Then:
+
+```sh
+forma remote whoami
+forma remote list
+forma remote pull engineering/platform.forma.json --output platform.forma.json
+forma remote push platform.forma.json
+```
+
+`forma mcp` is a local stdio bridge over that same authenticated API. Set `FORMA_ENABLE_MCP=true` only if you also want Streamable HTTP clients to POST to `/mcp` with a Bearer token. This release does not implement MCP OAuth discovery; prefer the stdio bridge when the client cannot set HTTP headers. Revoking a token in the editor blocks new operations immediately. File export/import still works if a user does not want to issue a token.
+
+Opening an imported file detaches its old library binding; save to a new path if one already exists. Remote pull/push keep a `.forma-remote.json` sidecar with the server, owner, path, and revision; a conflict means reread and reconcile rather than retrying blindly.
+
+Applied design systems live inside saved diagrams. In hosted mode, saved design presets last for the page session; export the design JSON to reuse it elsewhere. Shared organizational preset administration is not included yet. Agent tokens are stored hashed in `agent-tokens.json` at the data-directory root; include that file in backups.
+
+## Administration, backup, and recovery
+
+Data lives under `users/<opaque-subject-hash>/diagrams/` as native JSON. The sibling `identity.json` identifies the owner for the administrator. Ordinary users cannot access this metadata or other user directories through HTTP. Host administrators can read the disk; this is not end-to-end encrypted storage.
+
+Back up the entire data directory/volume, preserving ownership and permissions. Stop Forma for a consistent snapshot. Restore into a stopped instance; omit `.forma-host.lock` from a restored snapshot, then start and verify two users' files. Keep secrets and TLS backups separate from public source control. Test recovery periodically. Stop-before-copy also applies to administrative file moves or deletions; the app currently has no delete/retention UI.
+
+A clean shutdown removes `.forma-host.lock`. After an unclean shutdown the lock may remain. Confirm that every Forma process using that directory is stopped before removing that one lock file; never remove a live process's lock. Named Docker volumes can be inspected or mounted in a maintenance container by an administrator. Do not remove the users directory to clear a lock.
+
+Admission is `FORMA_ALLOWED_EMAILS` and/or `FORMA_ALLOWED_DOMAINS`. Domain access permits all users whose verified Google `hd` matches; use explicit emails when selective access is required. Existing files remain when admission is removed. On Node/`forma host`, changing the allowlist requires a process restart and in-memory sessions are cleared. On Vercel, change the env vars and redeploy; admission is re-checked on each API request. Sessions expire after 12 hours. Google account changes are checked on the next sign-in. Immediate offboarding is: update the allowlist, then restart or redeploy. Add internet-edge rate limiting/monitoring appropriate to your host; the application bounds sessions, login attempts, users, document sizes, and per-user storage, but is not a general denial-of-service protection service.
+
+## Verification boundary
+
+Tests and the visibly labeled local preview exercise simulated identities, real cookie sessions, private filesystem storage, quotas, and browser interactions. They do not claim to complete a live Google consent exchange. The deployment owner must supply an OAuth client and validate the real redirect, admission, and TLS configuration. No fake-auth switch is available in `forma host`.

package/docs/verification-v2.md

@@ -0,0 +1,41 @@
+# General engine verification
+
+Performed locally on 2026-09-20, after validating the original MVP. No remote CI run or external deployment is claimed.
+
+## Automated checks
+
+`npm run check` runs the original regression suite plus general-engine tests, TypeScript checking, and the static production build. The 19 tests cover v1 compatibility, explicit migration, strict style validation, style cascade precedence, transactional merges, preservation of human overrides, grid reflow, side ports, diagonal obstacle intersection, ellipse attachment, and every rendered gallery artifact. The original CLI file workflow remains covered.
+
+Every gallery artifact has zero errors and zero warnings from the inspector. The inspector measures geometric heuristics; it does not certify aesthetic quality. All eight PNGs were also visually reviewed. Refinements included moving a feedback loop to side ports, composing the mind map around its center, reducing excess export whitespace, increasing timeline breathing room, and fixing fixed-color text contrast under a dark design system.
+
+The seven repository skills passed the skill-creator validator. The initial Python environment lacked PyYAML; validation used a temporary virtual environment with PyYAML, without adding it to the product dependencies. Skills remain plain Markdown and harness-independent.
+
+## Actual graphical round trip
+
+1. Rendered `examples/gallery/development.forma.json` through the CLI and inspected the PNG.
+2. Opened that native file through the web editor's file chooser.
+3. Changed `verify` from **Verify & integrate** to **Verify with evidence** using its label control.
+4. Changed its fill to `#ffe5a3` using the appearance control.
+5. Dragged it graphically; the saved position is **x 568, y 336**.
+6. Downloaded the native document through Export. The result is preserved in `examples/roundtrip/human-edited.forma.json`.
+7. Applied `examples/roundtrip/agent-patch.json` via the CLI. It updates descriptions and adds the connector label **Evidence accepted**, without replacing human properties.
+8. Exported the result to SVG and PNG, with strict inspection reporting zero issues.
+9. Reopened it in the editor and verified the new description, label, fill, and pin. The complete result is `examples/roundtrip/agent-continued.forma.json`.
+
+Assertions against the actual downloaded file checked that the original node style object survived unchanged, the human fill override survived, and the complete presentation object was identical before and after the agent patch.
+
+## Static-client and design-system checks
+
+The production build was served at a nested `/forma/` path using Python's static HTTP server. The native v2 round-trip artifact loaded and rendered without an application backend. The visual identity selector changed the imported diagram to Signal while preserving content and explicit node styles. As documented, changing system geometry around absolute human pins can produce layout suggestions; no pin was silently discarded. The separate unpinned Signal gallery artifact demonstrates a clean complete restyle of identical content.
+
+CLI `migrate` and `style --system` were also exercised on the original v1 architecture artifact. The resulting document validated as v2. New CLI commands preserve atomic-write behavior.
+
+## Remaining limits
+
+- Only IBM Plex Sans is bundled and measured. Other font names survive editing but can use platform fallback; inspection warns about them.
+- Group heading dimensions are fixed. Context-specific style properties are documented rather than interpreted as arbitrary CSS.
+- The grid is content-sized and ordinal. Empty index gaps do not reserve tracks; timelines are not calibrated time-axis or scheduling tools.
+- Absolute pins can conflict after structural or design-system changes; inspection makes those conflicts visible.
+- Direct connectors do not avoid obstacles. Orthogonal routing has obstacle avoidance, but dense diagrams can still need refinement.
+- Crow's-foot markers, full sequence lifelines, reusable component definitions, and editable Office/draw.io exporters remain future work.
+- Large build-chunk warnings come from the lazy ELK bundle and editor dependencies. Runtime remains local and static.

package/docs/verification-v3.md

@@ -0,0 +1,16 @@
+# Usability release verification
+
+Verified locally on 2026-09-20 for v0.3.0.
+
+- `npm run check`: 20 tests, TypeScript, and production build pass. File-server integration covers nested files, revision conflicts, external edits, directory changes, stale workspace rejection, traversal/symlink rejection, Origin/Host restrictions, and required mutation headers.
+- Real browser: opened a diagram from a nested local folder, changed its title, saved it to disk, created and applied a custom gold design system, and saved again. Read the disk file to confirm both changes.
+- Changed that file externally. The editor rejected its stale save without discarding the draft. Refreshed Library and reopened the agent-modified document; the custom identity and individual overrides remained intact.
+- Saved a second file under a new subfolder and reloaded the page. The active save path survived the tab reload. Changed the source directory in the UI, created the missing folder, and saved there successfully.
+- Stopped the local server after the diagram loaded. Browser SVG and PNG exports both downloaded successfully; PNG displayed the success notification. Inspected the actual PNG: typography, group bounds, arrow routing, colors, and the individually dashed verification node remained correct.
+- Static-hosted build: saved a diagram to the browser library under a virtual subfolder. No local file server or account was required.
+- The in-app agent prompt includes installation, skill discovery, source folder, CLI verification, and human-edit preservation. Its copy button was exercised.
+- Packed the release and installed it to an isolated npm global prefix. From outside the repository, the installed `forma` created and rendered an architecture diagram with zero inspection warnings/errors, then served the packaged editor. Browser library tests ran against that installed editor.
+
+The export change removes the export-time font fetch and rejected-promise cache. The originally reported intermittent failure was not independently reproduced; the now-network-independent export path was directly verified with the server stopped.
+
+Known boundaries: one local folder server, explicit saves/refresh, optimistic file revision checks rather than cross-process transactions, and browser-local saved design presets. Local server restarts require reopening the file from Library. Static browser storage is not a backup. Google authentication and organizational server storage are deliberately deferred.

package/docs/verification-v4.1.md

@@ -0,0 +1,35 @@
+# Hosted agent-access verification
+
+Verified during the 0.4.1 implementation on 2026-09-21.
+
+## Automated checks
+
+`npm run check` passes all 27 tests, TypeScript, and the production build. Formatting and schema-regeneration checks also pass. New coverage in `tests/agent-access.test.ts` exercises:
+
+- Session-issued tokens that never store or list the secret, with hashed on-disk registry reload.
+- Folder scope, path containment, read-only denial, and cross-user isolation.
+- REST create/read/update with optimistic revision conflicts.
+- `forma remote` pull/push, sidecar binding, and refusal to push another user’s document.
+- Streamable HTTP MCP and stdio `forma mcp` over the same token, including revocation.
+- Token expiry and rejected remote origins.
+
+Existing hosted authentication, library isolation, quota, cookie, and local CLI tests remain green.
+
+## Browser and deployment boundary
+
+The Agent access UI is included in the production editor bundle. End-to-end clicks of token creation were not exercised in a live browser in this environment; the REST routes that UI calls are covered by the automated suite. Live Google sign-in, public TLS, and a production MCP client configuration still require the operator’s OAuth client and host, as in 0.4.0.
+
+See [self-hosting](self-hosting.md) and [ADR 006](decisions/006-hosted-agent-access.md).
+
+## Follow-up verification — 2026-09-27
+
+Revalidated release 0.5.2 at `6f2b611d1c9919d787a8ef02b36c60a03b3be3b2`.
+
+- A clean checkout passed all 42 tests, TypeScript, and the production build on Node 26.7.0. This includes REST, remote CLI, HTTP MCP, stdio MCP, user isolation, folder scope, read-only enforcement, revocation, and revision conflicts.
+- Exercised the production editor through `tests/fixtures/hosted-preview.ts`, using its explicitly labeled simulated identity provider. Opened **Agent access**, created a read-only token restricted to `verification` with a seven-day expiry, dismissed the one-time secret, and confirmed the displayed permissions and expiry.
+- Clicked **Revoke** and **Confirm revoke** and verified the connection disappeared. The test token was revoked; no secret was retained in screenshots or verification notes.
+- Visually inspected the rendered connection dialog after hiding the secret. Its fields, scope explanation, connection metadata, and revocation control were visible without clipping.
+
+The original browser-verification gap above is now closed. Live Google OAuth and a public deployment were not exercised in this follow-up. MCP currently uses manually configured bearer tokens, not an OAuth discovery/consent flow. Local CLI, local editor, and static use remain account-free.
+
+The original workspace had macOS-offloaded dependency and source files, causing reads to stall. Validation therefore ran from an independent checkout of the identical commit outside the synced Documents directory, with dependencies installed from the lockfile. The build emitted non-fatal upstream annotation and bundle-size warnings.

package/docs/verification-v4.2.md

@@ -0,0 +1,20 @@
+# Alignment verification
+
+Verified during the 0.4.2 implementation on 2026-09-21.
+
+## Automated checks
+
+`npm run check` passes all 31 tests, TypeScript, and the production build. Formatting checks also pass. New coverage in `tests/align.test.ts` and the CLI suite exercises:
+
+- Left alignment to the selection bounds and even-gap distribution.
+- Pinned near-alignment inspection on rows and columns, with merged x/y `--fix` pins.
+- Snapping an unpinned neighbor to a pinned edge without marking it pinned.
+- `forma align --left --ids` writing shared coordinates.
+
+Existing engine, gallery, hosted, and local-library tests remain green. Automatic layout is unchanged; near-alignment warnings apply to pinned nodes.
+
+## Browser and deployment boundary
+
+The editor bundle includes multi-select, the align bar, inspector actions, 8px snap matching the visible grid, and arrow-key nudge. Those UI paths were not clicked in a live browser in this environment; the core and CLI operations they call are covered by tests.
+
+Static hosting of `dist/` remains the account-free editor. Organizational Google sign-in still requires `forma host`.

package/docs/verification-v4.3.md

@@ -0,0 +1,5 @@
+# 0.4.3 distribution verification
+
+Verified 2026-09-21.
+
+`npm run check` and `npm publish --dry-run` pass on the 0.4.3 tree. Install docs, the agent setup prompt, and hosted update instructions use `npm install -g forma-diagrams` / `npm update -g forma-diagrams`. GitHub releases still attach a checksummed tarball. Publishing the GitHub release is intended to publish the same version to the npm registry via `.github/workflows/publish.yml`.

package/docs/verification-v4.md

@@ -0,0 +1,31 @@
+# Hosted-mode verification
+
+Verified during the 0.4.0 implementation on 2026-09-21.
+
+## Automated checks
+
+`npm run check` passes all 25 tests, TypeScript, and the production build. Formatting and schema-regeneration checks also pass. The suite runs the existing engine/CLI/local-library coverage and new hosted coverage. The hosted tests exercise:
+
+- Google authorization URL identity scopes, callback, S256 challenge, state, and nonce.
+- Browser-bound, single-use, expiring login attempts; provider failures and nonce mismatches fail closed.
+- Verified email and explicit admission allowlists; Workspace admission uses the `hd` claim.
+- Independent Alice/Bob libraries, denied cross-user reads/writes, and no absolute server paths in responses.
+- Native saves, optimistic revision conflicts, external agent edits, and preserved server files.
+- File and byte quotas; rejected writes do not create empty directories; simultaneous conflicting saves have only one winner.
+- Logout, session expiry, unauthenticated API rejection, canonical Host enforcement, required Origin and custom mutation headers, secure production cookie attributes, and data-directory process locking.
+
+The cryptographic ID-token verifier is Google's maintained library, not a custom implementation. Deterministic application tests inject an identity-provider boundary; they do not constitute a live Google consent exchange.
+
+## Browser checks
+
+A real browser used the compiled static editor and real hosted HTTP/file service through `tests/fixtures/hosted-preview.ts`. This fixture is visibly labeled **TEST PREVIEW · simulated identity provider**, alternates Alice and Bob, and is not included in release packages or reachable through `forma host`.
+
+Alice signed in, saved `engineering/alice.forma.json`, edited its title, saved again, and exported a PNG successfully under the hosted content policy. The file was confirmed on disk. Restarting the server required sign-in again, then Alice's saved diagram could be reopened from Library. Signing out also returned another open workspace tab to the sign-in page. Bob's subsequent sign-in opened an empty library with the default example, without recovering Alice's private diagram. Signing back in as Alice restored access to Alice's file.
+
+The sign-in page and hosted UI were inspected visually. Hosted mode uses server libraries and session-only design presets rather than local browser recovery. Existing local/static modes continue to use their previous storage behavior.
+
+## Deployment boundary
+
+The Docker build/start/restart/unauthenticated-API check passed in GitHub CI, alongside the Linux test/build checks. The npm release tarball was installed to an isolated prefix outside the repository; its hosted server served the editor and rejected unauthenticated library access, and its local CLI rendered a diagram with zero inspection errors/warnings. Compose and Caddy configuration validation are also included in CI. Docker is not installed on the development Mac, so local Node tests and isolated npm installs provide the local runtime verification.
+
+A live deployment still needs the operator's Google Web OAuth client, consent configuration, allowlist, domain, TLS, and durable disk. No such credentials or host were supplied in this phase; live Google sign-in and public TLS issuance are not claimed as verified. The supplied Compose/Caddy configuration and [operator guide](self-hosting.md) document the steps.

package/docs/verification-v5.1.md

@@ -0,0 +1,7 @@
+# 0.5.1 line editing verification
+
+Verified 2026-09-22.
+
+41 automated tests, the production build, and `npm publish --dry-run` pass. Install docs, the agent setup prompt, and hosted update instructions use the v0.5.1 GitHub release tarball. `forma-diagrams` is still not on the npm registry.
+
+0.5.1 lets a selected line be dragged onto any connection point and lets a straight stretch slide while its ends stay attached. Outline selection no longer blanks the canvas. The element inspector lists that shape's lines and hides document-wide theme and layout controls.

package/docs/verification-v5.2.md

@@ -0,0 +1,7 @@
+# 0.5.2 editing verification
+
+Verified 2026-09-22.
+
+42 automated tests, the production build, and `npm publish --dry-run` pass. Install docs, the agent setup prompt, and hosted update instructions use the v0.5.2 GitHub release tarball. `forma-diagrams` is still not on the npm registry.
+
+0.5.2 lets you resize a selected box, raises a selected line's handles above overlapping lines, and selects a box on the first click. Shift-click and the drag box select only what you aimed at. The sheet footer can be rewritten or hidden.

package/docs/verification-v5.md

@@ -0,0 +1,7 @@
+# 0.5.0 connector and text verification
+
+Verified 2026-09-21.
+
+40 automated tests, the production build, and `npm publish --dry-run` pass on the 0.5.0 tree. Install docs, the agent setup prompt, and hosted update instructions still use the GitHub release tarball. `forma-diagrams` is not on the npm registry; the 0.4.3 publish workflow failed with `ENEEDAUTH` because `NPM_TOKEN` is not available to Actions. Publishing the GitHub release will try that workflow again.
+
+0.5.0 adds evenly spaced connection points (one per side by default), optional pinned connector paths, routing that keeps existing bends and allows shared horizontal or vertical runs, shift-click multi-select, and text alignment on both axes.

package/docs/verification.md

@@ -0,0 +1,91 @@
+# MVP verification
+
+Verified locally on 2026-09-20 with Node 26.7.0 and the Codex in-app Chromium browser.
+The supported minimum runtime is Node 22; the included CI workflow targets Node 22.
+CI has not been run remotely as part of this local implementation.
+
+## Automated checks
+
+`npm run check` passes 14 tests, the strict TypeScript check and the static Vite build.
+`npm run format:check` passes. The tests include real CLI subprocesses and actual
+PNG signatures, not mocked exports.
+
+Covered behavior: schema versions, duplicate IDs, missing references, group cycles,
+transactional patches, cascade deletion, stable serialization, repeatable geometry,
+nested and negative-coordinate pins, long text, group heading bounds, branching,
+cycles, self-loops, disconnected graphs, XML escaping, connector attachment,
+overlap/collision/crossing reports, preservation of unrelated geometry after a pin,
+and rejection of oversized PNG exports.
+
+Both shipped examples pass `inspect --strict` with zero errors and zero warnings.
+
+## Agent → human → agent → export
+
+1. Created and rendered the architecture document using the shared engine/CLI.
+2. Opened the graphical editor. Renamed `gateway` from “API gateway” to “Public API”,
+   selected the violet accent, and dragged it to `{x: 440, y: 248}`.
+3. Downloaded the native `.forma.json` through the editor's Export menu.
+4. CLI-patched that actual downloaded file: updated the gateway description,
+   added a read replica, and connected the primary database to the replica.
+5. Asserted the original human label, violet color and exact pinned position survived.
+6. Inspected the seven-node, seven-edge result: zero errors and zero warnings.
+7. Exported it through the CLI to SVG and PNG, then reopened the native file in the editor.
+8. Verified the replica and updated description appeared while the pin remained.
+
+Local evidence files are under `output/`: `human-edited.forma.json`,
+`agent-update.json`, `roundtrip.forma.json`, `roundtrip.svg`, and `roundtrip.png`.
+These generated files are intentionally ignored by Git.
+
+## Graphical editing acceptance
+
+Started a blank document, added a service and database, renamed the service,
+connected their ports with a pointer drag, and edited the edge label and line style.
+Deleted the connection and restored it with Undo. Created a group and assigned a
+component to it. Confirmed arrow-key movement creates a persistent pin. Confirmed
+Cmd-S commits the field being edited before downloading the native document.
+
+Verified paper and midnight themes, both templates, pan/zoom/fit controls, source
+validation, native import/save, browser SVG/PNG exports and undo/redo. The source
+editor rejected version 99 while retaining the existing document. Undo restored
+the prior title, Redo reapplied it, and reloading recovered the last saved document.
+History itself is session-only and is not restored after a reload.
+
+## Static deployment and responsive check
+
+Built `dist/`, copied it under a `/forma/` directory, and served it with Python's
+plain HTTP server. There was no Vite runtime, application backend or database.
+The application rendered and exported PNG successfully from this subpath,
+confirming asset and embedded-font paths work on static hosts. No browser warnings
+or errors were recorded in the production check.
+
+Checked the normal 1280×720 viewport and a 390×844 narrow viewport. On narrow
+screens the file menu remains available and properties open as an overlay; zoom
+and pan remain available for diagrams wider than the screen. Desktop editing is
+the primary experience. The temporary viewport override was reset afterward.
+
+## Visual review
+
+Inspected actual exported PNGs and the running editor, rather than relying on
+DOM assertions alone. Reviewed typography/weights, text wrapping, container bounds,
+connector routing, label separation, emphasis, hierarchy and negative space.
+Fixed nested ELK edge coordinate offsets, group-title overflow, excessive compound
+whitespace, inconsistent variable-font rasterization, and lost keyboard positions.
+
+![Architecture export](images/architecture.png)
+
+![Release flow export](images/release.png)
+
+## Known limits
+
+- Layout inspection is a set of geometric heuristics, not a proof of visual quality.
+  Impossible pinned configurations remain pinned and produce diagnostics.
+- Layout runs locally in the browser; very large diagrams can occupy the main thread.
+  Small, focused diagrams are the quality target despite higher schema limits.
+- Bundled font coverage and advance metrics target Latin-script professional diagrams.
+  Full complex-script shaping and fallback fonts are not implemented.
+- The canonical file supports node color and position overrides; arbitrary vector
+  drawing, resizing, manual bend editing and live collaboration are outside this MVP.
+- PNG has explicit raster-size limits. SVG remains the scalable export.
+- VSDX, draw.io, PDF and PowerPoint exporters are extension points, not implemented features.
+- Vite reports the expected large ELK chunk and strips two upstream Zod annotation
+  comments during the build. These are build warnings; runtime checks pass.

package/examples/design-systems/atelier.json

@@ -0,0 +1,53 @@
+{
+  "version": 1,
+  "id": "atelier",
+  "name": "Atelier / editorial",
+  "revision": "1.0.0",
+  "canvas": {
+    "background": "#f7f5ef",
+    "text": "#242c29",
+    "secondary": "#69736b",
+    "border": "#d8ded4"
+  },
+  "spacing": {
+    "node": 44,
+    "layer": 80
+  },
+  "node": {
+    "shape": "rect",
+    "fill": "#fffef9",
+    "stroke": "#c7d0c3",
+    "text": "#243b30",
+    "secondary": "#657367",
+    "radius": 2,
+    "fontFamily": "IBM Plex Sans",
+    "fontSize": 16,
+    "padding": 22
+  },
+  "edge": {
+    "stroke": "#64776a",
+    "strokeWidth": 1.6,
+    "arrowEnd": "filled"
+  },
+  "group": {
+    "fill": "#eeeee5",
+    "stroke": "#cdd3c6",
+    "radius": 4,
+    "dash": "solid",
+    "text": "#526849"
+  },
+  "roles": {
+    "emphasis": {
+      "fill": "#dce9b9",
+      "stroke": "#a7be78"
+    },
+    "caution": {
+      "fill": "#fae4b6",
+      "stroke": "#d8b977"
+    },
+    "quiet": {
+      "fill": "#eeeee8",
+      "stroke": "#d0d3c9"
+    }
+  }
+}

package/examples/design-systems/signal.json

@@ -0,0 +1,53 @@
+{
+  "version": 1,
+  "id": "signal",
+  "name": "Signal / technical",
+  "revision": "1.0.0",
+  "canvas": {
+    "background": "#101c2e",
+    "text": "#eff6ff",
+    "secondary": "#99b0cb",
+    "border": "#31455f"
+  },
+  "spacing": {
+    "node": 48,
+    "layer": 96
+  },
+  "node": {
+    "shape": "rect",
+    "fill": "#192b43",
+    "stroke": "#3d5877",
+    "text": "#f1f7ff",
+    "secondary": "#a3bad3",
+    "radius": 16,
+    "fontFamily": "IBM Plex Sans",
+    "fontSize": 16,
+    "padding": 22
+  },
+  "edge": {
+    "stroke": "#77b9d2",
+    "strokeWidth": 2,
+    "arrowEnd": "open"
+  },
+  "group": {
+    "fill": "#142238",
+    "stroke": "#344960",
+    "radius": 20,
+    "dash": "dashed",
+    "text": "#9dcfe0"
+  },
+  "roles": {
+    "emphasis": {
+      "fill": "#164857",
+      "stroke": "#50b7bc"
+    },
+    "caution": {
+      "fill": "#56402c",
+      "stroke": "#cf9d60"
+    },
+    "quiet": {
+      "fill": "#1a2739",
+      "stroke": "#344960"
+    }
+  }
+}