feat: build publishable Relay npm package

.gitignore

@@ -21,3 +21,6 @@ Desktop.ini
 .mcpb/
 artifacts/*.mcpb
 integrations/claude-desktop/node_modules/
+assets/migrations/
+.artifacts/
+.codegraph/

.prettierignore

@@ -3,4 +3,4 @@ dist/
 coverage/
 pnpm-lock.yaml
 .superpowers/
-
+.codegraph/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krishna916
+
+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.

README.md

@@ -8,7 +8,7 @@ Agent integrations: see [setup](docs/agent-integration.md) and [troubleshooting]
 
 The approved agent-integration contract is documented in the [decision record](docs/decisions/0002-agent-integration-contracts.md), [MCP tool reference](docs/mcp-tools.md), [CLI reference](docs/cli-reference.md), and [session semantics](docs/session-semantics.md). The production MCP task tools and source-checkout CLI are shipped.
 
-Distribution planning is documented in the [Distribution decision](docs/decisions/0003-distribution-filesystem-and-lifecycle.md) and [Distribution contracts](docs/distribution/). The public npm package and operational distribution commands remain future work.
+Distribution planning is documented in the [Distribution decision](docs/decisions/0003-distribution-filesystem-and-lifecycle.md) and [Distribution contracts](docs/distribution/). Build and verify the local publishable tarball with the [npm package guide](docs/distribution/npm-package.md); registry publication remains a separate maintainer action.
 
 Relay is a local task sidecar for human–AI workflows. The current MVP is usable through its local web UI and through five safe local stdio MCP task tools.
 
@@ -70,8 +70,8 @@ It exposes five task tools—`task_capture`, `task_list`, `task_get`, `task_find
 
 Relay uses a local SQLite database containing task data. The default database file is:
 
-- Windows: `%APPDATA%\relay\relay.db`
-- macOS: `~/Library/Application Support/relay/relay.db`
+- Windows: `%LOCALAPPDATA%\Relay\relay.db`
+- macOS: `~/Library/Application Support/Relay/relay.db`
 - Linux: `${XDG_DATA_HOME:-~/.local/share}/relay/relay.db`
 
 Set `RELAY_DB_PATH` to use an explicit database file instead. Migrations run automatically when the HTTP/UI runtime starts. Connections enable foreign keys, WAL journal mode, and a 5-second SQLite busy timeout. Relay uses explicit SQL rather than an ORM.

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,6 @@
+# Third-party notices
+
+Relay includes open-source dependencies listed in `package.json` and their
+transitive dependencies. Their licenses and notices are installed alongside
+the package by npm/pnpm. This file identifies the application distribution's
+third-party notice location without duplicating dependency license text.

docs/distribution/npm-package.md

@@ -0,0 +1,61 @@
+# Relay npm package
+
+Issue #40 builds the local tarball for `@krishna916/relay`. Registry
+publication is deliberately not part of this workflow.
+
+## Build and inspect
+
+Use Node.js 24 and pnpm 10.2.0:
+
+```text
+pnpm pack:tarball
+pnpm verify:package:contents
+```
+
+The tarball is written to `.artifacts/npm/`. The positive `files` allowlist
+contains the compiled Node runtime, compiled React UI, SQL migrations,
+canonical skills, integration templates, README, license, and notices. It
+does not contain source, tests, databases, logs, secrets, repository metadata,
+or MCPB staging output.
+
+## Install from a tarball
+
+Install into a disposable prefix and invoke the installed command from a
+different directory:
+
+```text
+npm install --global --prefix <temporary-prefix> <absolute-path-to-tarball>
+<temporary-prefix>/bin/relay task list --output json
+<temporary-prefix>/bin/relay mcp
+<temporary-prefix>/bin/relay ui
+```
+
+On Windows the executable is `<temporary-prefix>\relay.cmd`. The package
+resolves immutable assets relative to its installed package root, while data,
+configuration, and cache paths are independent of the current directory.
+
+`RELAY_DB_PATH` must be an absolute path. It takes precedence over the
+platform default, and whitespace or relative values fail with usage/validation
+exit code 2. CLI, MCP, and UI use the same effective database path.
+
+## Supported runtime
+
+The initial release claim is Node.js 24 on Windows x64, macOS arm64, and
+Linux x64 with glibc. Windows arm64, macOS x64, Linux arm64, and Alpine/musl
+are not claimed. Native `better-sqlite3` installation and runtime evidence is
+required for each platform claim.
+
+If `better-sqlite3` cannot load, first confirm Node 24, then install the
+platform's native build tools, and reinstall the tarball into a clean prefix.
+Do not copy a repository-local `node_modules` directory into the installed
+package. A normal uninstall removes package files but retains Relay user data.
+
+## Human verification checklist
+
+- inspect the complete normalized tarball inventory
+- run the installed command from an unrelated directory
+- capture, list, get, session-capture, and one lifecycle mutation through the installed CLI
+- perform an MCP initialize/health handshake and confirm stdout is protocol-only
+- start the UI, confirm loopback binding, packaged index HTML, and health/version
+- record the temporary database path and native addon load result
+- run `pnpm verify`, `pnpm verify:package`, and the independent MCPB staging checks