@maudecode/kanvil 0.0.0-stage → 0.1.2

package/docs/self-hosting.md

@@ -0,0 +1,204 @@
+# Self-hosting
+
+Kanvil runs as one application service and PostgreSQL 18. Tickets, comments, authentication, durable events, and attachment bytes live in PostgreSQL. PocketID is optional; local login remains available alongside OIDC.
+
+## Install from npm
+
+Requires Node `>=24.22.0 <25` and a PostgreSQL 18 server. The package includes the backend, built web app, and schema migrations; pnpm and a source checkout are unnecessary.
+
+```sh
+npm install --global @maudecode/kanvil
+mkdir kanvil-instance
+cd kanvil-instance
+kanvil configure --production https://kanvil.example.com
+```
+
+`configure` creates a mode-600 `.env` in the current directory and refuses to overwrite it. Edit `DATABASE_URL` to point at your PostgreSQL database, using a role that owns the database and can run schema migrations. For a PostgreSQL service on the same host, an administrator can create it with `createuser --pwprompt kanvil` and `createdb --owner=kanvil kanvil`. Set `DATABASE_URL=postgres://kanvil:URL_ENCODED_PASSWORD@127.0.0.1:5432/kanvil` and `HOST=127.0.0.1` in `.env`. The generated `POSTGRES_PASSWORD` belongs to the Compose path; use the password you assigned to the standalone database role instead.
+
+```sh
+kanvil start
+```
+
+Run from the instance directory so the CLI reads its `.env`. Startup defaults to production mode and applies migrations before listening. `kanvil migrate` applies migrations without starting HTTP; `kanvil recover --email admin@example.com` prompts privately for a replacement local password. `kanvil --version` reports the installed package version. Use a service manager to keep the process running, with the instance directory as its working directory and the absolute path from `command -v kanvil` as its executable. Run it as an unprivileged account that can read the configuration.
+
+For an upgrade, back up PostgreSQL and `.env`, stop the service, install the desired version with `npm install --global @maudecode/kanvil@VERSION`, then restart from the same instance directory. `@latest` selects the latest stable release. Keep the same database URL and authentication secret. See the standalone backup instructions below before upgrading.
+
+## Install the published Docker image
+
+Install Docker with Compose. No Node installation or source checkout is required. In an empty instance directory, download `compose.yml` from the [release's tagged source](https://github.com/MaudeCode/kanvil/tags). Replace `X.Y.Z` with a published version:
+
+```sh
+kanvil_version=X.Y.Z
+curl -fL "https://raw.githubusercontent.com/MaudeCode/kanvil/v${kanvil_version}/compose.yml" -o compose.yml
+```
+
+Create `.env` with an HTTPS origin and independent secrets:
+
+```sh
+umask 077
+cat > .env <<EOF
+KANVIL_URL=https://kanvil.example.com
+POSTGRES_PASSWORD=$(openssl rand -hex 32)
+BETTER_AUTH_SECRET=$(openssl rand -hex 48)
+KANVIL_SETUP_TOKEN=$(openssl rand -hex 32)
+KANVIL_IMAGE=ghcr.io/maudecode/kanvil:latest
+EOF
+docker compose pull
+docker compose up -d --wait
+```
+
+The image supports Linux amd64 and arm64. Replace `latest` with a release version such as `0.1.0`, or pin `ghcr.io/maudecode/kanvil@sha256:YOUR_DIGEST` for an immutable deployment.
+
+The app binds to loopback port 5180; change the host port with `KANVIL_PORT`. Set up the HTTPS reverse proxy below before opening the site. The application runs as the `node` user with a read-only root filesystem and temporary `/tmp`. Its health check verifies database connectivity. PostgreSQL storage is kept in the `postgres-data` volume. `docker compose down` retains that volume; removing volumes deletes instance data.
+
+For source builds, use the repository's Node/pnpm versions and run:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm configure --production https://kanvil.example.com
+docker compose -f compose.yml -f compose.build.yml up -d --build --wait
+```
+
+Keep both `-f` arguments on subsequent Compose operations for a source-built instance.
+
+## First owner and configuration
+
+Open the site, enter `KANVIL_SETUP_TOKEN` from your private configuration, and create the owner account. Setup closes after the first account exists. Create additional accounts in Administration → Users, then grant workspace access from the account detail sheet or workspace settings. Projects can inherit workspace roles or keep explicit private membership. Existing projects stay private when upgrading; see [workspaces](workspaces.md). Remove the setup token from configuration after onboarding if desired.
+
+Retain `.env` securely. `BETTER_AUTH_SECRET` is required to read encrypted authentication state after restoration. It also encrypts saved integration credentials. Changing it is a deliberate credential rotation, not a routine upgrade. Both install paths serve the web app, API, MCP, and realtime at the same origin.
+
+## HTTPS and streaming
+
+Serve Kanvil at its own origin. A Caddy example is:
+
+```caddyfile
+kanvil.example.com {
+    reverse_proxy 127.0.0.1:5180
+}
+```
+
+With nginx, forward the original host and protocol, turn off response buffering for SSE, and allow persistent streaming connections:
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:5180;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_buffering off;
+    proxy_read_timeout 1h;
+}
+```
+
+Keep `KANVIL_URL` equal to the public HTTPS origin. Add `KANVIL_TRUSTED_ORIGINS` only for additional browser clients you explicitly operate. Web, API, MCP, login, consent, and realtime use the same application origin. No separate message broker or search service is required.
+
+Signed-in sessions and MCP OAuth clients may make `KANVIL_SESSION_WRITE_LIMIT` write requests per minute (120 by default) before receiving `429 rate_limited`; API keys are limited separately by the authentication layer. The counter is per application process.
+
+## PocketID / OIDC
+
+Create a confidential OIDC client in PocketID, enable PKCE, and register:
+
+```text
+https://kanvil.example.com/api/auth/callback/oidc
+```
+
+Set all three values together in `.env`, then recreate the app:
+
+```dotenv
+OIDC_DISCOVERY_URL=https://identity.example.com/.well-known/openid-configuration
+OIDC_CLIENT_ID=your-client-id
+OIDC_CLIENT_SECRET=your-client-secret
+OIDC_NAME=PocketID
+```
+
+Sign in locally and explicitly link PocketID from account settings. Public signup and implicit account linking are closed. Use HTTPS for the provider, including native sign-in; the Expo integration requires it. The provider's ID-token signature is verified. For a private certificate authority, add a `compose.override.yml` pointing at its public certificate:
+
+```yaml
+services:
+  app:
+    environment:
+      NODE_EXTRA_CA_CERTS: /certificates/identity-ca.pem
+    volumes:
+      - ./identity-ca.pem:/certificates/identity-ca.pem:ro
+```
+
+Native devices must also trust that authority. Never mount the authority's private key.
+
+## Instance administration
+
+Administrators can edit the instance name and description, manage accounts, and configure local/S3 file storage, PostgreSQL/Elasticsearch search, and PostgreSQL/RabbitMQ event delivery in Administration. See [optional infrastructure](infrastructure.md) for deployment variables, adapter interfaces, recovery behavior, and S3 backup requirements. OIDC, public URL, and push credentials remain deployment settings.
+
+## Optional mobile push
+
+Set `KANVIL_PUSH_ENABLED=true` to enable the Expo push transport. If the Expo project has push access-token security enabled, also set its server-held `EXPO_ACCESS_TOKEN`. Recreate the app after changing configuration. A signed mobile build must contain the public Expo project ID and have APNs/FCM credentials configured; see [mobile setup](mobile.md). Accounts opt in through Settings and register each device separately.
+
+Push is disabled by default. Ticket storage, login, Inbox, realtime, and MCP work without Expo services. Push messages use a generic update notice and ticket identifiers, without ticket titles, descriptions, comments, or evidence. The database outbox commits with each subscribed event, checks current account/project/session/subscription access before every send, retries failures, and checks Expo receipts. Expired login sessions and explicit session revocation remove their device registrations. A failed or interrupted transport may deliver duplicates; queued notices expire after one day. Delivery status is available in the `push_deliveries` table. Backups contain device tokens, so protect them alongside authentication state.
+
+## Backup
+
+For a published Docker installation, run from the instance directory:
+
+```sh
+umask 077
+docker compose exec -T db pg_dump -U kanvil -d kanvil --format=custom > /secure/location/kanvil.dump
+```
+
+Use a new output filename and check that `pg_dump` succeeds before treating it as a backup. Replace `kanvil` after `-d` if `KANVIL_DATABASE` differs. For npm installations, use PostgreSQL 18 client tools against the configured database:
+
+```sh
+umask 077
+pg_dump --host=127.0.0.1 --username=kanvil --dbname=kanvil --format=custom --file=/secure/location/kanvil.dump
+```
+
+Supply authentication through a protected `.pgpass` or a password prompt. Keep `.env` and any external S3 backups alongside the database backup. For a source checkout, the existing wrapper refuses to overwrite backup files:
+
+```sh
+pnpm backup --output /secure/location/kanvil.dump
+```
+
+The command uses the PostgreSQL tools inside the database container to create a consistent custom-format archive. It includes locally stored attachment/photo bytes, pending external uploads, authentication tables, and encrypted integration settings. Completed S3 uploads need a separate backup of each referenced bucket. The output is private and existing files are never overwritten. Keep the original instance configuration, especially `BETTER_AUTH_SECRET`, securely with your backup. Copy backups off the application host using your normal protected backup storage.
+
+## Restore without replacing the original database
+
+Stop the application before switching databases. For a published Docker install:
+
+```sh
+docker compose stop app
+docker compose exec -T db createdb -U kanvil kanvil_restored
+docker compose exec -T db pg_restore -U kanvil -d kanvil_restored --exit-on-error --single-transaction < /secure/location/kanvil.dump
+```
+
+For npm, stop the service, create an unused database with `createdb --host=127.0.0.1 --username=kanvil kanvil_restored`, then run `pg_restore --host=127.0.0.1 --username=kanvil --dbname=kanvil_restored --exit-on-error --single-transaction /secure/location/kanvil.dump`. Change `DATABASE_URL` in the instance `.env` to the restored database, retain the original authentication secret, and restart the service. A failed restore leaves the new target available for inspection; keep the original database.
+
+For the source wrapper, restore into a new, unused database name:
+
+```sh
+pnpm restore --file /secure/location/kanvil.dump --database kanvil_restored
+```
+
+The command refuses existing databases and restores in a single transaction. If it fails, the newly created target remains available for inspection; the previous database is retained. After a successful restore, set `KANVIL_DATABASE=kanvil_restored` in `.env`, retain the original authentication secret, and switch the application:
+
+```sh
+docker compose up -d --no-deps --wait app
+```
+
+Check login, tickets, attachment downloads, and consumer access before deleting any old database. Compose constructs the runtime `DATABASE_URL` from `POSTGRES_PASSWORD` and `KANVIL_DATABASE`; the `DATABASE_URL` entry in `.env` is also available for standalone Node operations. Use `COMPOSE_PROJECT_NAME` consistently if you operate multiple Compose instances.
+
+## Account recovery
+
+A host operator can replace an existing account's local password:
+
+```sh
+docker compose exec app node dist/recover.mjs --email admin@example.com
+```
+
+The password is entered privately. For local source development, use `pnpm account:recover --email admin@example.com`. The command uses Better Auth's password format and revokes that account's sessions. Its role, linked OIDC account, and API credentials are retained. Revoke agent credentials separately if an account was compromised. Passwords are never accepted as command-line arguments.
+
+## Updates and validation
+
+Back up first and review changes. For published images, set the desired `KANVIL_IMAGE` in `.env`, then run `docker compose pull app` and `docker compose up -d --no-deps --wait app`. Source builds use `docker compose -f compose.yml -f compose.build.yml up -d --build --wait`. Startup applies the committed schema migrations under a database advisory lock. Database migrations and the application version should be upgraded together. Restore a backup into a new database if an incompatible database change requires rollback.
+
+`pnpm test:docker` builds the image and starts an isolated Compose instance with generated test secrets. A real browser creates an owner, project, and ticket; the official MCP client connects; then the test recovers the account, backs up and restores into a new database, and verifies sessions, scoped credentials, tickets, and original attachment bytes. It also checks that existing backup files and databases are refused. Its containers and test volumes are removed afterward.
+
+For standalone Node hosting, run `pnpm build`, provide the same configuration through the environment, and run `NODE_ENV=production pnpm --filter @kanvil/server start`. Use a PostgreSQL 18 service you operate and include its database in your backup process. The Docker backup/restore commands target the Compose database service.
+
+Project icon rendering uses a bundled offline Lucide collection through Iconify. It does not require an external icon API. Icon license notices are served at `/third-party-icons.txt`; Kanvil remains MIT licensed.

package/docs/themes.md

@@ -0,0 +1,38 @@
+# Appearance and themes
+
+Kanvil's default **Aligned** palette uses neutral light/dark surfaces and an indigo accent. The layout follows Linear's [current interface guidance](https://linear.app/now/behind-the-latest-design-refresh): compact headers, quieter navigation, softer separators, and more information in each row. Kanvil keeps its own branding and shadcn components.
+
+Choose Light, Dark, or System under **Settings → Appearance**. Search the theme gallery by name. Choices and custom themes persist in this browser. The default respects the system appearance; switching palettes does not change that preference.
+
+The picker follows T3 Code's System/Light/Dark preview tiles and paired color orbs. A light or dark orb assigns a theme only to that appearance; System switches between the two saved choices. Selecting a theme entry applies both appearances and clears the mix. Rings and sun/moon markers indicate the assigned appearances without checkmarks. Theme entries expose duplicate actions, plus edit, export, and delete actions for custom themes. Create theme starts from the current light/dark mix; Add theme imports the existing version-one JSON format. Removing a custom theme resets only appearances that used it. T3 Code's MIT notice for the adapted preview artwork is included in `/third-party-themes.txt`.
+
+## Bundled palettes
+
+| Theme                               | Light / dark palette source                                                                                        |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Aligned                             | Kanvil's adaptation of Linear's neutral interface                                                                  |
+| Catppuccin Mocha, Macchiato, Frappé | [Catppuccin](https://github.com/catppuccin/palette); Latte in light mode                                           |
+| Solarized                           | [Ethan Schoonover's Solarized](https://ethanschoonover.com/solarized/)                                             |
+| GitHub                              | [GitHub Primer](https://github.com/primer/primitives)                                                              |
+| Dracula                             | [Dracula and Alucard](https://github.com/dracula/dracula-theme)                                                    |
+| One Dark                            | [Atom One Dark](https://github.com/atom/one-dark-syntax) and [One Light](https://github.com/atom/one-light-syntax) |
+| Nord                                | [Nord](https://www.nordtheme.com/docs/colors-and-palettes/)                                                        |
+| Tokyo Night, Tokyo Night Storm      | [Tokyo Night](https://github.com/folke/tokyonight.nvim); Day in light mode                                         |
+| Gruvbox                             | [Gruvbox](https://github.com/morhetz/gruvbox)                                                                      |
+| Rosé Pine, Rosé Pine Moon           | [Rosé Pine](https://rosepinetheme.com/palette/); Dawn in light mode                                                |
+| Everforest                          | [Everforest](https://github.com/sainnhe/everforest)                                                                |
+| Monokai                             | [Monokai](https://github.com/tanvirtin/monokai.nvim); a Kanvil light adaptation                                    |
+| Night Owl                           | [Night Owl and Light Owl](https://github.com/sdras/night-owl-vscode-theme)                                         |
+| Ayu                                 | [Ayu](https://github.com/ayu-theme/ayu-colors)                                                                     |
+
+These are interface adaptations, not editor syntax themes. Backgrounds and accent families come from the upstream palettes; shades are adjusted where needed for readable buttons and text. Derived surfaces, sidebar text, muted text, and status colors use the shared theme helper. Tests enforce at least 4.5:1 text contrast across the principal surfaces in both modes. Palette notices ship at `/third-party-themes.txt`.
+
+Old built-in selections resolve to the corresponding named palette. The former default selections, including `linear`, resolve to Aligned. Existing custom themes keep their IDs and colors, and their version-one JSON import/export format is unchanged.
+
+## Density
+
+Tickets are grouped into collapsible status sections with counts. Ordering applies within each status. All matching tickets are shown, with no pagination or Load more controls.
+
+Ticket lists default to Compact rows. **Display → Row spacing → Comfortable** adds room without hiding titles or labels. **Display → Label display → All labels** shows every full label and scope inline, wrapping as needed. Property visibility, row spacing, and label display are personal browser preferences. Search, filters, and ordering remain shareable through the URL and saved views. Touch controls retain their larger targets on phones.
+
+The ticket list uses one view/action toolbar under the location bar. The project name appears once in the location bar, beside its settings cog. Open the magnifying glass for search and the view dropdown for saved views, saving the current filter, deleting a selected saved view, or selecting all displayed tickets. On narrow screens, metadata shares a line instead of repeating property headings. Label/scope previews show two tags on wider layouts and one on narrow layouts; opening a preview reveals every full tag. Ticket titles remain unclipped.

package/docs/verification.md

@@ -0,0 +1,83 @@
+# Initial delivery verification
+
+Kanvil's implementation is contained in this repository, under the MIT license. It uses its own PostgreSQL storage and has no Kaneo dependency or import requirement. External agent runners adopt its documented interfaces separately.
+
+## Delivered behavior
+
+- Projects, stable ticket keys, wrapping titles, Markdown requirements, assignment, labels/scopes, parent/child context, blockers, related/duplicate tickets, comments, activity, attachments, subscriptions, saved views, search/filtering, pagination, bulk edits, archiving, and deletion.
+- Shared versioned HTTP/OpenAPI and MCP operations, permission-filtered durable SSE replay, snapshot recovery, optimistic concurrency, idempotent writes, eligibility reasons, exclusive claims, renew/release/recovery, and attributed evidence.
+- React web and Expo native apps with local/OIDC login, explicit account linking, secure native sessions, live updates, cached reading, and local drafts.
+- Agent-aware Inbox preferences and optional session-bound push registration/delivery, with a transactional outbox, retries, receipts, and access checks.
+- Non-root Docker application plus PostgreSQL, private configuration generation, migrations, local account recovery, and tested backup/restore including attachment bytes.
+- Runnable scoped MCP and durable realtime reference consumers, native build profiles, CI, and operator documentation.
+
+## Evidence
+
+| Area                   | Verification                                                                                                                                                                                                                                                                                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Repository checks      | `pnpm check`: formatting, linting, TypeScript, and 44 tests across six suites. Tests use isolated databases.                                                                                                                                                                                                                          |
+| Domain and permissions | Concurrent/stale writes, idempotent retries, competing/expired claims, persistent ownership fencing, dependency cycles, project/credential isolation, attachment bytes, and account recovery/session revocation.                                                                                                                      |
+| Browser and OIDC       | Chromium workspace flows with 55-ticket pagination, wrapping titles, drafts, stale edits, attachments, credential revocation, hierarchy navigation, actual PocketID virtual-passkey linking/login, and interactive MCP OAuth consent/PKCE.                                                                                            |
+| Realtime and consumers | Ordered replay, live changes, abort/reconnect behavior, service restart, persisted projection checkpoints, expired-cursor snapshots, scoped MCP reads, and stream revocation without consuming per-frame API allowance. Both reference CLI entry points were executed against an isolated server.                                     |
+| Self-hosting           | Actual Compose image startup, browser owner/project/ticket creation, official MCP connection, bundled password recovery, revoked sessions, private backups, restoration into a new database, retained sessions/credentials, exact binary attachment readback, and refusal to overwrite backups/databases.                             |
+| iOS                    | Development and standalone Release simulator builds. Release code-signature verification, embedded bundle, HTTPS/local login, native system-browser PocketID linking and sign-in, complete ticket context, session restoration, and cached reading. Metro was stopped during Release validation.                                      |
+| Android                | Standalone arm64 Release APK compiled by the preview workflow, APK signature verified, embedded JavaScript verified, artifact and MIT license retained. Both native Hermes exports and Expo dependency compatibility checks pass.                                                                                                     |
+| Push                   | Isolated-transport tests with real PostgreSQL cover outbox commits, receipt processing, retries, access changes between sends, session revocation, shared-device account changes, omitted-field compatibility, ticket-deletion notices, and explicit unsubscribe cancellation. Native preference changes were read back through HTTP. |
+
+The release configuration and Android artifact checks are recorded in [PR #12](https://github.com/MaudeCode/kanvil/pull/12). Implementation was committed in coherent slices and merged after review and green CI.
+
+## Boundaries
+
+Production deployment and app-store publication have not been performed. Existing real PocketID accounts and signing credentials were not used; identity-provider checks used a disposable instance.
+
+No physical-device installation or runtime validation has been performed. Android emulator execution and device passkeys also remain unvalidated. Preview APKs use a generated debug signing key. iOS simulator signing is ad hoc; real distribution needs operator-owned signing configuration.
+
+Real APNs/FCM delivery and notification-tap routing remain unvalidated. They require an Expo project and authorized push/signing configuration. Push is optional and disabled by default; ticket storage, login, Inbox, realtime, and MCP work without it.
+
+The reference mirror refreshes a full project snapshot when changes arrive. It is an example of consistent recovery, not an execution scheduler. Apps retain explicit local drafts; offline edits are not automatically submitted. Rich-text editing, custom workflow designers, and separate search/message-broker services remain outside the agreed initial scope.
+
+## Interface redesign
+
+The web and iPhone interfaces share the palette and brand geometry described in [the design direction](design.md). Web fonts are bundled locally with their OFL license. Existing controls and renderers were extended; ticket mutations and authentication contracts retain their shared implementations.
+
+- Chromium regression coverage checks light/dark appearance at 1440, 1024, 650, 390, and 320 pixels, including complete long/unbroken titles, viewport and table overflow, selection, expandable filters, persisted/system theme changes, reduced motion, and keyboard navigation into the main content.
+- An independent WebKit run checked local sign-in, both themes at the same five widths, accessible table rows, complete title bounds, and selection.
+- Projects, account settings, project settings, and Inbox were inspected at desktop and phone widths. Both themes, ticket details, wrapping title editors, and empty states were captured. These checks found no browser exceptions or page-level horizontal overflow. Create/update contract and persisted-search regressions also verify that pasted line breaks become single-line title text. Shared text colors meet a 4.5:1 contrast ratio against both canvas and surface colors in each theme.
+- The redesigned standalone iOS Release app was built, signed, and run with an isolated HTTPS backend. Local sign-in, project and ticket navigation, the header project sheet, status picker, Markdown preview, and native edit/save were exercised. A separate HTTP client confirmed the edited title and incremented version. Session restoration after reinstall/relaunch, dark appearance, and large Dynamic Type ticket reading after relaunch were inspected.
+
+The existing 44 tests and browser workspace/OAuth workflows pass. CI additionally exercises the disposable PocketID workflow and self-hosting smoke test. Android runtime is outside this redesign; physical-device, push-delivery, and production boundaries above still apply.
+
+## Reproduce
+
+The approved anvil is applied to web/native brand components, application and launch-screen assets, favicons, touch/install icons, share metadata, and the README. Branding browser coverage checks the actual self-hosted asset URLs, loaded font, manifest icons, and absolute share-image URLs on root and nested pages. The iOS Release build with build number 2 was installed and its home-screen icon and native branding inspected in both themes; launch-screen resources were generated, compiled, and observed during a recorded cold launch of that binary. See [branding](branding.md) for the source and regeneration command.
+
+Use [CONTRIBUTING.md](../CONTRIBUTING.md) for checks and disposable fixtures, [self-hosting](self-hosting.md) for Compose/backup/recovery, [native builds](mobile.md) for simulator/preview/signing setup, and [examples](../examples/README.md) for external consumer integration.
+
+## Workspaces, identity, icons, and account administration
+
+The workspace/account update was verified locally without publishing a branch or deployment:
+
+- `pnpm check`: formatting, linting, workspace TypeScript checks, and 76 passing tests. The two optional live-service tests remain conditional on their isolated infrastructure fixtures.
+- `pnpm test:oidc`: 20 browser workflows passed, including disposable PocketID linking/login, interactive MCP consent/PKCE, workspace switching and deep links, inherited/private access, project icon selection/upload/reset, user administration, and role-dependent cache cleanup.
+- `pnpm test:docker`: packaged browser/API/MCP checks and database backup/restore passed, including workspace association, attachment bytes, and uploaded project icon bytes.
+- PostgreSQL tests upgrade populated pre-workspace data without widening private access; cover inherited/explicit roles, guest and scoped-key isolation, revoked membership, retry receipts, concurrent administrator changes, and library/image validation and cleanup protection.
+- Account tests exercise name/email search, filters, safe response fields, last-administrator protection through role/update/ban/delete paths and normalized URLs, password/session changes, public-profile role restrictions, and concurrent role edits.
+- Rendered project/workspace settings, member directories, user lists/detail sheets, icon selection, and API-key project choices were reviewed in light/dark at 1440, 390, and 320 pixels. Fixes included circular clipping, cached profile photos, sidebar label/prefix overlap, long identity wrapping, and narrow-container settings layouts.
+- Native account role parsing and persisted-cache versions share the same administrator-role rule. This update does not claim a new physical-device installation or validation.
+
+All integration fixtures use disposable test-owned databases/accounts. Existing project identifiers and ticket prefixes are retained. Local review remains separate from publication approval.
+
+## Linear layout and named palettes
+
+The web app now uses compact shared controls, navigation, table rows, settings rows, and typography. Compact and Comfortable ticket density are personal browser preferences. Table layout remains available on laptop widths, with the title taking the remaining space; phone layouts retain wrapping titles and larger touch targets. The shadcn inset sidebar, resizing, keyboard access, and contextual actions remain in use.
+
+The default palette is Aligned. Eighteen named themes have light/dark mappings and a searchable gallery. Built-in palette checks cover body, sidebar, muted, secondary, popover, primary-button, and status-text contrast. Custom JSON import/export remains version one, and old built-in IDs resolve to named replacements. Sources and notices are listed in [themes](themes.md).
+
+Validation for this pass:
+
+- `pnpm check` passes formatting, linting, all workspace type checks, and 80 tests. Two optional live-service suites remain skipped.
+- `pnpm test:e2e` passes 24 browser workflows, including all 18 palettes in both appearances, system appearance, theme persistence, custom import/export, searchable theme choices, compact/comfortable density, list properties, selection, relationships, authentication, and the existing ticket/account/settings workflows.
+- Playwright captured the main page families in both modes at desktop and phone widths. Additional project/workspace/member/user/account/icon checks include 320px layouts. Captures are local under `dist/ui-review/linear-pages`, `dist/ui-review/workspaces-users`, and `dist/ui-review/linear-redesign`; they are not tracked.
+- Existing local preview content was checked through the LAN app. Selection caused zero row movement at 1440px, 390px, and 320px; these checks found no page-level horizontal overflow or browser exceptions.
+
+This pass validates the web app. It does not claim a new native build, physical-device validation, or production publication.

package/docs/workspaces.md

@@ -0,0 +1,21 @@
+# Workspaces and project access
+
+A Kanvil instance hosts accounts and deployment settings. Workspaces group projects and have their own name, URL key, and members. Personal settings belong to the account. Instance administrators can administer every workspace and project; workspace administrators cannot administer the instance or other workspaces.
+
+Workspace roles reuse the existing Read only, Can edit, and Admin roles. Workspace-visible projects inherit workspace roles. Private projects require explicit project membership, except that workspace administrators can manage all projects in their workspace. Explicit project roles override inherited roles, except for workspace administrators. A person with only project membership can see that project and its workspace identity without receiving workspace-wide access.
+
+Removing workspace membership also removes that person's explicit memberships in the workspace's projects. Keep at least one workspace administrator. Project-scoped API keys remain bounded to their configured projects and cannot administer an entire workspace. Ticket and project prefixes remain unique across the instance, preserving existing links and key-based API lookups.
+
+Existing projects are assigned to a default workspace and remain private. Existing project membership is retained; only instance administrators gain workspace administration automatically. Existing API calls that omit a workspace choose an accessible writable workspace; when none exists, project creation creates a personal workspace for the caller. New web-created projects select their workspace explicitly and offer workspace or private access.
+
+Workspace operations use the same operation registry, authorization, transaction lock, idempotency receipts, and HTTP/MCP implementations as projects. Realtime visibility continues to derive from accessible projects, so revoked membership stops event delivery. Workspace changes invalidate project consumers through project events; an empty workspace also refreshes in browser queries on focus.
+
+Project icons can use a bundled, searchable open-source icon collection or a normalized image upload. Uploaded bytes use the existing blob storage adapter and authenticated project access. Referenced icons must remain excluded from orphan cleanup, and backup/restore retains them with other blob objects.
+
+## Verification
+
+- Upgrade populated databases without widening private project access or changing ticket identifiers.
+- Test workspace and private-project isolation, inherited versus explicit roles, scoped API keys, removal, last-admin guards, and idempotent writes through the shared domain.
+- Exercise workspace discovery through HTTP and MCP and access revocation through realtime replay and image routes.
+- Test workspace switching, deep links, settings navigation, member search and role changes, icon selection/upload/removal, and account administration in browser workflows.
+- Review light/dark desktop and phone layouts with real content. Keep publication separate from local verification.

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@maudecode/kanvil",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Open-source, self-hosted ticketing for agents and people.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.22.0 <25"
+  },
+  "type": "module",
+  "bin": {
+    "kanvil": "bin/kanvil.mjs"
+  },
+  "files": [
+    "bin",
+    "apps",
+    "docs",
+    "compose.yml"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaudeCode/kanvil.git"
+  },
+  "homepage": "https://github.com/MaudeCode/kanvil#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "3.1152.0",
+    "@better-auth/api-key": "1.7.8",
+    "@better-auth/cimd": "1.7.8",
+    "@better-auth/drizzle-adapter": "1.7.8",
+    "@better-auth/expo": "1.7.8",
+    "@better-auth/mcp": "1.7.8",
+    "@hono/node-server": "2.1.5",
+    "@hono/zod-openapi": "1.6.3",
+    "@iconify-json/lucide": "1.2.144",
+    "@inquirer/password": "5.2.3",
+    "@modelcontextprotocol/server": "2.3.1",
+    "amqplib": "2.2.0",
+    "better-auth": "1.7.8",
+    "drizzle-orm": "0.45.4",
+    "expo-server-sdk": "7.2.0",
+    "hono": "4.13.13",
+    "pg": "8.23.1",
+    "zod": "4.6.7"
+  }
+}