@maudecode/kanvil 0.2.1 → 0.3.0

package/docs/localization.md

@@ -0,0 +1,25 @@
+# Languages
+
+The web and native apps read in 21 languages: Azərbaycan dili (`az-AZ`), Deutsch (`de-DE`), Ελληνικά (`el-GR`), English (`en-US`), Español (`es-ES`), Français (`fr-FR`), हिन्दी (`hi-IN`), Bahasa Indonesia (`id-ID`), Italiano (`it-IT`), 日本語 (`ja-JP`), 한국어 (`ko-KR`), Македонски (`mk-MK`), Nederlands (`nl-NL`), Polski (`pl-PL`), Português (Brasil) (`pt-BR`), Русский (`ru-RU`), Türkçe (`tr-TR`), Українська (`uk-UA`), Tiếng Việt (`vi-VN`), 简体中文 (`zh-CN`), and 繁體中文 (`zh-TW`).
+
+Choose one under **Settings → Preferences → Language** on the web or **Settings → Language** in the native app. **System default** follows the browser's or device's preferred languages: an exact match, then the same language (Traditional Chinese scripts and regions choose `zh-TW`), then English. The web choice belongs to the browser and also applies to the sign-in page; the native choice belongs to the device. Signing out or changing servers keeps it.
+
+Only presentation changes. API values, saved filters and views, URLs, ticket content, names, keys, and identifiers stay as they are. Dates, times, numbers, relative times, calendar month and weekday names, and the first day of the week follow the interface language; **Week starts on** defaults to **Language default** and can still be set to Sunday, Monday, or Saturday. Error codes the server explains in English (`forbidden`, `not_found`, `version_conflict`, `claim_conflict`, `rate_limited`, and others listed in `translatedErrors`) read in the interface language; any other server message is shown as sent. Client-side validation messages come from Zod's catalog for the language. Rendered Markdown and ticket titles take their direction from their own text, so right-to-left content stays readable in any language.
+
+The server, MCP tools, notifications it sends, and the API documentation stay in English.
+
+## Catalogs
+
+`packages/contracts/src/i18n` holds the locale list (`locales`, `localeDetails`), the i18next instance, `applyLocale`, the formatters (`formatDate`, `dateFormat`, `formatNumber`, `formatRelativeTime`, `firstWeekday`), and one directory per locale. Each directory has the same sections: `common` (contract values and generic actions shared by web and native), `shell`, `ticket`, `detail`, `settings`, and `admin` for the web, and `native` for the native app. English (`en-US`) is the source and the fallback for any missing key; other catalogs load only when chosen.
+
+Contract label tables such as `stateLabels`, `priorityLabels`, `kindLabels`, `difficultyLabels`, `roleLabels`, `permissionLabels`, `relationChoices`, and `eventLabels` read the active language each time an entry is read, so web and native share one wording and the server keeps English. `apps/web/src/lib/locale.tsx` and `apps/mobile/src/locale.tsx` save the choice, load the catalog (and on the web the calendar wording), and remount the app below `LocaleRoot` when the language changes.
+
+## Adding strings
+
+Call `t("section.group.key", values)` from `@kanvil/contracts/i18n` and add the English text to that section in `en-US`, then to every other locale. Write complete sentences with `{{placeholders}}`; never join translated fragments. Use `{{label, lowercase}}` where English lowercases a label mid-sentence. Plurals use i18next keys with `count`: English has `_one` and `_other`, and each locale has exactly the categories its plural rules use (for example Russian `_one`, `_few`, `_many`, `_other`; Japanese only `_other`). Text with embedded elements uses `Trans` with named tags such as `<link>`. Text built at module load must read the language at render time instead.
+
+`pnpm check` runs `packages/contracts/src/i18n/i18n.test.ts`, which fails when a locale lacks or adds a key, has the wrong plural categories, changes a placeholder or tag, or leaves a value empty, and checks the locale resolution, fallback, label, format, and error behavior.
+
+## Adding a locale
+
+Add its identifier to `locales` with its name and CLDR first weekday in `localeDetails`, a directory with every section, a loader in `catalogs`, its Zod messages in `validation`, and its calendar wording in `apps/web/src/lib/locale.tsx`. The catalog test then requires every key and plural form.

package/docs/plan.md

@@ -10,7 +10,7 @@ Judge the product by how reliably agents can discover work, obtain complete cont
 
 Build a self-hosted ticketing system with web and native mobile apps, local login, PocketID-compatible OIDC, a documented HTTP API, durable realtime events, and MCP tools.
 
-Start with a fresh workspace and native ticket storage. Kaneo compatibility, data import, and changes to T3 Code or Factory are outside this project. External consumers receive documented interfaces and example clients maintained in this repository.
+Start with a fresh workspace and native ticket storage. Projects export to a versioned JSON bundle and import from one into a new project through a previewed, restart-safe run; sources from other trackers translate into that bundle. Kaneo compatibility beyond such import sources and changes to T3 Code or Factory are outside this project. External consumers receive documented interfaces and example clients maintained in this repository.
 
 Use established libraries and the smallest implementation that meets the acceptance criteria. Each ticket operation, permission check, validation rule, and event write has one shared implementation across HTTP and MCP. Web and mobile share contracts and client logic while using platform-appropriate rendering and navigation.
 
@@ -30,9 +30,13 @@ Pin the latest stable compatible releases during implementation. Reuse existing
 
 - First-owner setup, account management, local login, logout, and account recovery.
 - Closed public registration by default.
-- Local email/password and OIDC login available on web and mobile.
+- Local email/password and OIDC login available on web and mobile, plus optional GitHub, Google, and Discord sign-in for linked accounts and emailed sign-in and password-reset codes when SMTP is configured.
 - PocketID setup through discovery URL, client ID, server-held secret, and documented callback URLs.
 - Explicit account linking and consistent project authorization across login methods.
+- Custom workspace roles with granular, server-enforced actions, assigned through the member editor and capped by the assigning member's own role and credential scopes.
+- Workspace owners who transfer ownership to another active administrator and delete the workspace after a reviewed impact summary, a recent sign-in, and a typed confirmation.
+- Account deletion by the person or an instance administrator after a reviewed impact summary, a recent sign-in, and a typed email: it removes every way to sign in or act as the account and its personal details, and keeps shared history attributed to a `Deleted account` tombstone.
+- Expiring, revocable email invitations to a workspace or selected projects, accepted once by the account with the invited address; they never open registration.
 - Secure mobile session storage and tested browser-to-app authentication callbacks.
 - Revocable credentials with project and operation scopes for unattended consumers.
 - Authenticated and permission-filtered HTTP, realtime, attachment, and MCP access.
@@ -41,12 +45,16 @@ Validate PocketID mobile login and MCP client authentication early. These checks
 
 ## Ticket operations
 
-- Projects and stable ticket keys with permanent links.
+- Projects and stable ticket keys with permanent links. Project administrators archive and restore projects, move them to another workspace they administer with a reviewed access, label, and follow preview, and delete them after a reviewed impact summary; ticket keys never change or get reused.
 - Titles, Markdown descriptions, acceptance criteria, and attachments.
-- Status, priority, kind, difficulty, scopes, labels, and assignment.
+- Status, priority, kind, difficulty, scopes, labels (per project or shared across a workspace), and assignment.
+- Per-project workflow states that administrators add, rename, recolor, reorder, recategorize, and delete with an explicit reassignment. Each maps to one canonical status, which every open, closed, readiness, claim, and filter rule reads, so status-only clients keep working.
+- Typed project custom fields (text, number, date, checkbox, select, and multi-select) that administrators define, order, and edit with required rules and defaults. Definitions are versioned and server-validated; removing a used option needs an explicit destination for its values, so nothing is erased silently.
 - Parent/child relationships, blockers, related tickets, and duplicate references.
-- Comments, activity history, subscriptions, archiving, and deletion behavior.
-- Search, filtering, sorting, pagination, and bulk edits.
+- Comments, activity history, subscriptions, duplication, archiving, and deletion behavior.
+- Versioned JSON export of a project's tickets and a previewed import into a new project that resumes after interruption without duplicates and notifies no one.
+- Read-only Linear, Jira (Cloud and Data Center), Trello, Plane, PLANKA, and Kaneo import sources that translate a team, project, or board into the same bundle and disclose what Kanvil cannot hold.
+- Workspace search across projects, tickets, comments, and activity with a results page; any-of and none-of property filters shared by lists, search, and saved views; sorting, pagination, and bulk edits.
 - Optimistic concurrency checks that prevent silent overwrites.
 - Idempotent writes that remain safe when a client retries a request.
 
@@ -79,15 +87,25 @@ Deliver reference consumers and contract tests within Kanvil. External applicati
 
 ## Web and mobile
 
-- Web list with readable wrapping titles, adjustable columns, filters, selection, bulk actions, and keyboard navigation.
-- Ticket detail view containing requirements, relationships, discussion, attachments, activity, and supplied evidence.
-- Project settings, account settings, and notification preferences.
+- Web list with readable wrapping titles, adjustable columns, filters, selection, keyboard navigation, a preview sheet that shows the full ticket detail over the list and opens from every ticket reference in the app, shared public views included, and atomic bulk actions for status, priority, assignee, kind, difficulty, labels (replace or clear), due date (set or clear), archiving or restoring, and deletion. Mixed selections show as mixed, never as the first row's value. Each status section selects as a whole.
+- A server-kept manual order for tickets within a project and projects within a workspace: an explicit Manual sort in the URL and saved views, with drag and drop, keyboard moves, and menu commands across the list, board, and planning views.
+- Project planning view with complete Planned (backlog) and Archived groups, moving planned work to To do, restoring archived tickets, and a way back to active work.
+- Start and due dates on tickets, with read-only Calendar (month) and Timeline (six-week) layouts of a project's filtered tickets, period navigation and Today, and project calendar feeds that administrators share and revoke as iCalendar links. Drag-to-reschedule and dependency editing on the timeline stay out of scope.
+- Ticket detail view containing requirements, relationships, editable links, discussion, attachments, activity, and supplied evidence.
+- Read-only public links that project administrators turn on and off under Project settings, showing anyone with the link the project's unarchived tickets and their requirements, properties, labels, dates, and relationships, without people, discussion, attachments, or coordination details.
+- Ticket composer that can target any writable project and stay open to create several tickets in a row.
+- Custom fields edit through one property component in the composer, detail sidebar, list cells (shown from the Display menu), board cards, and selection toolbar, filter through the shared filter picker, and read on native ticket screens.
+- Comment mentions: typing `@` in a comment offers the project's members and inserts a `mention:` link that renders as "@Name"; mentioned members are notified even when they do not follow the ticket, and the Inbox has a Mentions view.
+- Inbox that opens an update's ticket in the same preview sheet, with its discussion and reply composer, and marks entries read or unread, dismisses them, clears read entries, and marks all read, from the keyboard as well.
+- Home overview of your assigned work, recent activity, and project progress, with a complete My work list across the workspace's projects grouped by due date or project.
+- One settings navigation for account, current workspace, projects, and instance administration (shown only where the server grants access), including personal and notification preferences: Inbox and push, personal channels (email, ntfy, Gotify, signed webhooks) routed per workspace or project, per-category flags, and a due-soon reminder lead, with overdue notices. Project administrators send ticket activity to signed webhooks, Slack, Discord, Mattermost, or Telegram. One outbox delivers all of them. Project administrators also connect GitHub, Gitea, and GitLab repositories through one set of operations and one settings form, with self-managed instance URLs for Gitea and GitLab: signed webhooks attach verified branch, pull request, and issue links to the tickets they name and can move those tickets to a mapped workflow state through the normal versioned update; the outbox checks access and posts optional link comments. Issue sync keeps tickets and issues in step both ways under label-scoped rules that administrators preview before applying; links that lose their labels or change on both sides stop for a reviewed reconciliation, and ambiguous issue creations are never repeated. The `?` help and the `⌘K` palette read one action catalog, so labels and keys match.
 - Native mobile lists and navigation, ticket editing, comments, attachments, deep links, and notifications.
 - Live updates while connected, recovery after disconnection, cached reading, and locally saved drafts.
 - Shared client operations, validation, formatting, design tokens, and status presentation rules.
+- The web and native interfaces in 21 languages from shared catalogs, with a per-browser or per-device language choice; dates, numbers, and the first weekday follow it while API values and ticket content stay unchanged ([languages](localization.md)).
 - Accessible controls, responsive layouts, useful loading/error states, and explicit connection status.
 
-Start with Markdown editing and an established renderer. Rich-text editing remains an optional scope decision. Defer automatic submission of offline edits and custom workflow designers. Optional external storage, search, and broker adapters are described in [infrastructure](infrastructure.md); the default deployment still requires only PostgreSQL.
+Start with Markdown editing and an established renderer. Markdown fields carry a formatting toolbar with shortcuts, and people who can write a ticket toggle its description and acceptance checklists in place; the stored text stays canonical Markdown. The web app adds an optional Visual mode (Tiptap) to the same fields: formatting and `/` block menus, tables, checklists, highlighted code, Mermaid diagrams, mentions, and inline images and files that use the attachment service, staged until a new ticket exists. Visual mode reads and writes the same Markdown string and leaves text it cannot represent exactly, such as raw HTML or footnotes, in the Markdown editor. Rendered Markdown highlights code, draws Mermaid diagrams in strict mode, and shows embedded images; links to other sites stay links, so viewing a ticket contacts no third party. Native apps keep reading and editing the canonical Markdown. Defer automatic submission of offline edits and visual workflow designers; workflow states are edited as a list in project settings. Optional external storage, search, and broker adapters are described in [infrastructure](infrastructure.md); the default deployment still requires only PostgreSQL.
 
 ## Self-hosting and verification
 

package/docs/self-hosting.md

@@ -1,6 +1,6 @@
 # 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.
+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, GitHub, Google, Discord, and emailed codes.
 
 ## Install from npm
 
@@ -123,15 +123,54 @@ services:
 
 Native devices must also trust that authority. Never mount the authority's private key.
 
+## GitHub, Google, and Discord
+
+Each built-in provider turns on when both of its values are set, and appears on the web and native sign-in screens and in account settings in that order, after the OIDC provider. Register the matching callback URL with each provider's OAuth app:
+
+```text
+https://kanvil.example.com/api/auth/callback/github
+https://kanvil.example.com/api/auth/callback/google
+https://kanvil.example.com/api/auth/callback/discord
+```
+
+```dotenv
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+DISCORD_CLIENT_ID=
+DISCORD_CLIENT_SECRET=
+```
+
+These providers only sign in accounts that linked them: sign in another way, then link the provider in account settings. They never create an account or claim one with the same email, whatever **Automatically create users from SSO** says, and the provider must have verified the email. GitHub and Google sign-in uses state and PKCE; Discord uses state. Google's ID token is checked against Google's signing keys, issuer, audience, and age, and posted ID tokens are refused.
+
+## Email codes and password reset
+
+With `SMTP_URL` and `SMTP_FROM` set and password sign-in enabled, the sign-in screens offer **Email me a sign-in code** and **Forgot password?**. Both email a six-digit code and a link that opens the page the request started on, such as an invitation, with that code filled in. A code works once, expires after 10 minutes, and is discarded after three wrong attempts. Asking again while a code is valid mails the same code and restarts its 10 minutes, so a resend never invalidates a code already received; codes are stored encrypted with `BETTER_AUTH_SECRET`. Codes reach existing, enabled accounts only: an unknown, disabled, or deleted address gets the same answer and no email, and each address receives at most three codes per 15 minutes per application process (an email the relay refuses does not count). Resetting a password signs out every session of the account. Deleting an account or changing its address discards its outstanding codes, and an account under a ban cannot use a code, whenever it was issued.
+
+The first code sign-in to an account whose email was never verified removes the account's password, linked providers, and sessions before signing in, so access that predates proof of the mailbox does not carry over. Accounts created by an administrator start unverified; a password reset verifies the email without removing anything.
+
+Better Auth also limits these endpoints per client IP when `NODE_ENV=production` (three requests per minute for sending codes). Behind a reverse proxy, forward the client address in `X-Forwarded-For`.
+
 ## 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.
+Administrators can edit the instance name and description, manage accounts, review every workspace with its administrators and member/project counts (Administration → Workspaces) and manage its members without joining it, 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 outbound notifications
+
+People can add notification channels in Settings → Notifications (ntfy, Gotify, a signed webhook, or email), and project administrators can send ticket activity to Slack, Discord, Mattermost, Telegram, or a signed webhook from Project settings → Integrations. Nothing is sent until someone configures a channel or destination; see [the API reference](api.md#notification-channels-and-project-destinations) for routing, signing, retries, and health.
+
+- Email channels need an SMTP relay: set `SMTP_URL` (for example `smtp://user:password@mail.example.com:587`, or `smtps://` for implicit TLS) and `SMTP_FROM` (for example `Kanvil <kanvil@example.com>`). Without them the email option is hidden.
+- Outbound HTTP refuses loopback and private-network addresses. Set `KANVIL_DELIVERY_ALLOW_PRIVATE=true` when channels must reach services on your own network, such as a LAN ntfy or Gotify. Only enable it when everyone who can add a channel or destination may reach those hosts.
+- Project administrators can also connect GitHub, Gitea, and GitLab repositories under Project settings → Integrations. The code host must reach `KANVIL_URL` to deliver webhooks; set `KANVIL_GITHUB_API_URL` for GitHub Enterprise Server. Gitea and GitLab connections name their own instance URL; a self-managed instance on a loopback or private address also needs `KANVIL_DELIVERY_ALLOW_PRIVATE=true`. See [repository connections](api.md#repository-connections).
+- Workspace writers can import Linear teams, Jira, Plane, and Kaneo projects, and Trello and PLANKA boards with their own credentials, which are never stored. The server must reach `api.linear.app`, `api.trello.com`, or the tracker's site; a self-hosted Jira, Plane, PLANKA, or Kaneo on a private network needs `KANVIL_DELIVERY_ALLOW_PRIVATE=true`. Plane and Kaneo limit requests per minute, so reading a large project can take minutes: let a reverse proxy keep `/api/v1/workspaces/*/imports/source` open that long. See [export and import](api.md#export-and-import).
+- Channel and destination settings and repository tokens and webhook secrets, including signing secrets, are encrypted with a key derived from `BETTER_AUTH_SECRET`. Keep that secret with your backups; without it the saved settings cannot be decrypted and must be entered again.
 
 ## 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.
+Push is disabled by default. Setting `KANVIL_PUSH_ENABLED=false` again also stops sends to devices registered earlier; their queued notices end as `push_disabled`. Ticket storage, login, Inbox, realtime, and MCP work without Expo services. Push messages use a generic update or mention 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 (a mention needs no subscription), 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 `deliveries` table. Backups contain device tokens, so protect them alongside authentication state.
 
 ## Backup
 
@@ -187,7 +226,7 @@ Check login, tickets, attachment downloads, and consumer access before deleting
 
 Administration → Authentication controls **Email and password sign-in** and **Automatically create users from SSO** independently. Defaults keep password sign-in enabled and SSO provisioning disabled. Public email signup is always closed. Changes apply to subsequent authentication requests without restarting; sessions and scoped credentials keep their existing lifecycle.
 
-Before disabling password sign-in, configure OIDC and explicitly link the acting administrator's provider account in User settings. A binding must match the configured provider's issuer and client ID; relink the administrator after changing either. New SSO users require a provider-verified email and receive the ordinary user role with no workspace or project membership. A matching local email requires explicit account linking. Existing linked users can sign in with provisioning disabled. While password sign-in is disabled, users must retain at least one binding for the configured provider; enable password sign-in before unlinking the last one.
+Disabling password sign-in also turns off email codes and password reset. Before disabling it, configure OIDC and explicitly link the acting administrator's provider account in User settings. A binding must match the configured provider's issuer and client ID; relink the administrator after changing either. New SSO users require a provider-verified email and receive the ordinary user role with no workspace or project membership. A matching local email requires explicit account linking. Existing linked users can sign in with provisioning disabled. While password sign-in is disabled, users must retain at least one binding for the configured provider; enable password sign-in before unlinking the last one.
 
 ## Account recovery
 
@@ -197,7 +236,7 @@ A host operator can replace an existing account's local password:
 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.
+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. A deleted account cannot be recovered: its tombstone has no address to match. Passwords are never accepted as command-line arguments.
 
 Password recovery alone does not enable password sign-in. If the IdP is unavailable, a host operator can recover an active administrator and explicitly re-enable password sign-in with `--enable-password-sign-in` on the same recovery command. For example, `pnpm account:recover --email admin@example.com --enable-password-sign-in` for source development, or append that flag to the Docker command above. This updates the persisted policy and revokes the recovered account's sessions atomically, without restarting. Sign in locally, repair the deployment's OIDC settings, verify linking and SSO login, then disable passwords again in Administration. Keep host access and an active local administrator recovery account available.
 

package/docs/themes.md

@@ -33,6 +33,6 @@ Old built-in selections resolve to the corresponding named palette. The former d
 
 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.
+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, label display, and grouping are personal browser preferences, also under **Settings → Preferences** with the first day of the week for date pickers and the sidebar state on launch. Both places change the same values; **Reset preferences** restores the defaults. 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

@@ -34,7 +34,7 @@ No physical-device installation or runtime validation has been performed. Androi
 
 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.
+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. Custom workflow designers and separate search/message-broker services remain outside the agreed initial scope; the web Visual editor stores canonical Markdown.
 
 ## Interface redesign
 

package/docs/workspaces.md

@@ -2,14 +2,26 @@
 
 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.
+Every workspace starts with the Read only, Can edit, and Admin roles. Administrators add custom roles under Workspace settings → Roles, each a chosen set of actions: edit tickets, delete tickets, manage projects, members, invitations, sharing, or the workspace. Members get any of them through the same member editor, on the workspace or on one project. Nobody grants an action their own role lacks, only administrators grant Admin, and a role held by anyone is deleted only after choosing the role its members move to. Clients show what the server reports a role allows, never what its name suggests. Workspace-visible projects inherit workspace roles. Private projects require explicit project membership, except that workspace administrators can manage all projects in their workspace; a custom role never reaches private projects through the 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.
+Workspace administrators can also invite an email address that has no access yet. An invitation fixes its role and covers either the whole workspace or selected projects, and its link works once, before it expires, for the account with that email. Kanvil account emails are set by instance administrators or verified by the OIDC provider, and people cannot change their own, so the email match identifies the recipient. Accepting checks again that the sender still administers the workspace, grants only the invited access to projects that still exist, and keeps any higher role the person already has. Invitations follow the instance's sign-in policy: they never create an account or open registration. The link is emailed when SMTP is configured and can always be copied from the dialog shown after sending; resending replaces it.
+
+A project moves to another workspace only when the caller administers both. Direct project members keep their roles; access inherited from the old workspace ends and the destination's applies, which the move preview lists person by person. See [the API reference](api.md#project-lifecycle).
+
+Every workspace has one owner, an active administrator. The owner, or an instance administrator, transfers ownership to another active administrator and deletes the workspace; the previous owner stays an administrator. The owner cannot be removed, demoted, disabled, or have their account deleted until ownership moves, so a workspace never loses its owner silently. Deleting a workspace needs a sign-in within the last 15 minutes and the typed URL key, lists every project and what goes with it first, and refuses while any ticket is claimed. Its projects are deleted as project deletion does, its memberships, invitations, and shared labels go, and accounts stay. See [the API reference](api.md#workspace-ownership-and-deletion).
+
+When ownership was introduced, each existing workspace went to its earliest-created active administrator member, ties broken by account ID. A workspace without one has no owner until an instance administrator transfers it to an active administrator.
+
+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. A project administrator can change a prefix and move tickets between writable projects of one workspace; earlier prefixes stay reserved and earlier keys keep resolving, so existing links and key-based API lookups keep working without reaching past current access.
 
 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.
 
+Workspace administrators can define labels every project in the workspace uses, beside each project's own labels. Projects show workspace labels read-only in their label settings; renaming or deleting one updates every project's tickets and saved views together. See [the API reference](api.md) for conflict and adoption rules.
+
+Anyone who can read a project can export its tickets as JSON from the project's settings. Workspace writers import such a file, or a Linear team, a Jira, Plane, or Kaneo project, or a Trello or PLANKA board, into a new project from the workspace's settings. For a tracker, connect with what it asks for (an API key or token, a site address, or a PLANKA password), which is used only while the form reads the source and is never saved, then pick the team, project, or board and whether to include comments. The preview lists what maps, what changes, and what the import leaves out before anything is written, and the import continues in the background, resuming after a restart. See [Export and import](api.md#export-and-import).
+
 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
@@ -17,5 +29,9 @@ Project icons can use a bundled, searchable open-source icon collection or a nor
 - 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 shared label catalogs, access-filtered counts, cross-project renames and deletions, claims, and same-name adoption.
+- Test ownership transfer, owner removal, demotion, and account-disable guards, concurrent transfer and removal, and workspace deletion previews, blockers, recent sign-in, and tombstones.
+- Test invitation creation, resend, revocation, expiry, email mismatch, sender demotion, concurrent acceptance, and the acceptance page.
+- Test custom roles: seeded roles on upgraded memberships, granular actions, credential ceilings, grants beyond the actor, immediate revocation, stale edits, reserved names, deletion with reassignment, private projects, and owner and last-administrator guards.
 - 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,6 @@
 {
   "name": "@maudecode/kanvil",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Open-source, self-hosted ticketing for agents and people.",
   "license": "MIT",
   "engines": {
@@ -26,23 +26,27 @@
   },
   "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",
+    "@better-auth/api-key": "1.7.10",
+    "@better-auth/cimd": "1.7.10",
+    "@better-auth/drizzle-adapter": "1.7.10",
+    "@better-auth/expo": "1.7.10",
+    "@better-auth/mcp": "1.7.10",
     "@hono/node-server": "2.1.5",
     "@hono/zod-openapi": "1.6.3",
-    "@iconify-json/lucide": "1.2.144",
+    "@iconify-json/lucide": "1.2.145",
     "@inquirer/password": "5.2.3",
     "@modelcontextprotocol/server": "2.3.1",
     "amqplib": "2.2.0",
-    "better-auth": "1.7.8",
+    "better-auth": "1.7.10",
     "drizzle-orm": "0.45.4",
     "expo-server-sdk": "7.2.0",
     "hono": "4.13.13",
+    "i18next": "26.5.2",
     "jose": "6.2.12",
+    "mdast-util-from-markdown": "2.1.0",
+    "nodemailer": "10.1.2",
     "pg": "8.23.1",
+    "turndown": "7.2.4",
     "zod": "4.6.7"
   }
 }