absolutepraya · absolutepraya · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026
diff --git a/.coderabbit.yaml b/.coderabbit.yaml
@@ -131,7 +131,7 @@ reviews:
         - Do not treat upstream Karakeep behavior as authoritative when this fork intentionally diverges.
         - Flag contradictory setup, contributor, deployment, or operator instructions.
 
-    - path: "docs/fork-setup.md"
+    - path: "docs/operator-setup.md"
       instructions: |
         - Keep fork, development, and deployment facts aligned with the other canonical repository guidance when those facts change.
         - Do not treat upstream Karakeep behavior as authoritative when this fork intentionally diverges.

diff --git a/.env.sample b/.env.sample
@@ -1,12 +1,12 @@
-# See https://docs.karakeep.app/configuration for more information
+# See the repository documentation for configuration details.
 DATA_DIR=<path>
 NEXTAUTH_SECRET=<secret>
 
 # Operator helper for pulling the full prod state into local development.
 # Real values belong only in .env.
 KARAKEEP_PROD_SSH_HOST=vps
 KARAKEEP_PROD_SSH_USER=
-KARAKEEP_PROD_COMPOSE_DIR=/home/praya/karakeep
+KARAKEEP_PROD_COMPOSE_DIR=/home/praya/marka
 KARAKEEP_PROD_COMPOSE_SERVICE=web
 KARAKEEP_PROD_EXPORT_IMAGE=alpine:3.20
 EMBEDDING_ENABLE_AUTO_INDEXING=false

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
@@ -2,7 +2,7 @@ name: Build and Push image
 
 # Pull-based deploy: this workflow builds + pushes version-compatible web and
 # workers images to GHCR. The VPS runs Watchtower, which polls those tags and
-# redeploys both Karakeep services without an inbound SSH deploy step.
+# redeploys both Marka services without an inbound SSH deploy step.
 
 on:
   workflow_run:

diff --git a/.wt/config.toml b/.wt/config.toml
@@ -1,19 +1,17 @@
 worktree_path = ".worktrees"
 port_offset_interval = 100
 max_slots = 9
+name_strategy = "cities"
+branch_template = "{user}/{name}"
+default_base = "origin/main"
 
-# Each worktree receives a separate environment, persisted-state copy, ports,
-# and Docker container names. setup-worktree.sh snapshots the main workspace's
-# local data, which can be refreshed from production with `pnpm prod:pull-state`
-# before creating a worktree.
-#
-# The generated .env is intentionally worktree-local and gitignored. Its
-# DATA_DIR and service endpoints use WT_PORT_BASE, preventing concurrent
-# worktrees from sharing state or ports.
+# Setup prepares isolated dependencies and local state only. It does not start
+# a development server or any long-running service.
 setup = [
   "pnpm install --frozen-lockfile",
   "bash \"$WT_ROOT_PATH/scripts/setup-worktree.sh\"",
   "ln -sfn ../../.env apps/web/.env",
   "ln -sfn ../../.env apps/workers/.env",
   "ln -sfn ../../.env packages/db/.env",
 ]
+teardown = []
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,12 +1,12 @@
 # Marka assistant context
 
-`absolutepraya/marka` is the Marka fork. The upstream Karakeep project is <https://github.com/karakeep-app/karakeep>.
+`absolutepraya/marka` is the Marka repository.
 
 ## Authoritative documentation map
 
-- `README.md`: public fork framing
+- `README.md`: public product framing
 - `CONTRIBUTING.md`: contribution rules
-- `docs/fork-setup.md`: fork operation, local development, and deployment
+- `docs/operator-setup.md`: operator setup, local development, and deployment
 - `docs/README.md`: docs-site development
 - This file, `CLAUDE.md`, and `GEMINI.md`: concise assistant operations context
 
@@ -18,7 +18,7 @@
 - Start local development with `pnpm dev:start`. Use `pnpm dev:start -d` for detached mode and `pnpm dev:stop` to stop only that workspace.
 - Shared local infrastructure is machine-level: one Meilisearch at `http://localhost:7700` and one Chrome/CDP at `http://localhost:9222`. Manage it explicitly with `pnpm dev:infra:up`, `pnpm dev:infra:status`, and `pnpm dev:infra:down`.
 - Parallel worktrees keep separate SQLite/assets data and unique web ports. `scripts/setup-worktree.sh` assigns each worktree a unique `MEILI_INDEX_PREFIX`; both `bookmarks` and `bookmarks_vectors` use that namespace on the shared Meilisearch server.
-- `pnpm dev:start` defaults the main workspace namespace to `main_`. Outside the fork dev launcher, an unset `MEILI_INDEX_PREFIX` preserves the original `bookmarks` and `bookmarks_vectors` index names.
+- `pnpm dev:start` defaults the main workspace namespace to `main_`. An unset `MEILI_INDEX_PREFIX` is a compatibility fallback for the original `bookmarks` and `bookmarks_vectors` names; manual `web` or `workers` starts outside `pnpm dev:start` must set an explicit unique prefix.
 - Run focused checks before broad checks when practical. Standard checks are `pnpm format:fix`, `pnpm lint`, `pnpm typecheck`, and `pnpm test`.
 - Validate shared-dev shell behavior with `bash scripts/dev-infra.test.sh`.
 - Root `.env` is canonical. Do not print or commit secrets.
@@ -28,9 +28,9 @@
 
 Preserve package scopes, database paths, export-format names, `KARAKEEP_` variables, Compose service names, GHCR image paths, and Docker-network names. These are operations and compatibility identifiers, not product presentation.
 
-The fork deploys through CI-built GHCR images and VPS Watchtower polling. The canonical production compose is `deploy/docker-compose.prod.yml`; use `docs/fork-setup.md` for the complete operator workflow.
+Marka deploys through CI-built GHCR images and VPS Watchtower polling. The canonical production Compose file is `deploy/docker-compose.prod.yml`; use `docs/operator-setup.md` for the complete operator workflow.
 
-Karakeep is a monorepo bookmark-everything app for saving and retrieving links, notes, images, PDFs, highlights, and archived pages.
+Marka is a monorepo bookmark library for saving and retrieving links, notes, images, PDFs, highlights, and archived pages.
 
 Main stack:
 - **Frontend:** Next.js, React, TypeScript, Tailwind CSS
@@ -63,15 +63,15 @@ Main stack:
 The preferred portable setup for a new self-hosted instance is `scripts/install.sh`. The public one-line entry point is:
 
 ```bash
-curl -fsSLo /tmp/karakeep-setup.sh https://raw.githubusercontent.com/absolutepraya/marka/main/scripts/install.sh && bash /tmp/karakeep-setup.sh
+curl -fsSLo /tmp/marka-setup.sh https://raw.githubusercontent.com/absolutepraya/marka/main/scripts/install.sh && bash /tmp/marka-setup.sh
 ```
 
 Important installer facts:
 
 - supported host scope is Linux `amd64` with Docker Engine, Docker Compose v2, and OpenSSL already installed
 - the script never installs Docker, changes firewall rules, configures DNS, or provisions TLS/reverse-proxy infrastructure
-- default configuration directory is `~/karakeep`; default persistent data directory is `~/karakeep/data`
-- generated Compose project name is `karakeep`
+- default configuration directory is `~/marka`; default persistent data directory is `~/marka/data`
+- generated Compose project name remains `karakeep` for compatibility
 - generated app images are the paired `ghcr.io/absolutepraya/marka:web-main` and `ghcr.io/absolutepraya/marka:workers-main` tags
 - the default web listener is `127.0.0.1:3000`, intended to sit behind an operator-managed reverse proxy for Internet-facing installs
 - search choices are managed Meilisearch, external Meilisearch, or disabled search
@@ -91,7 +91,7 @@ Validate installer changes with:
 bash scripts/install.test.sh
 ```
 
-## Local development for this fork
+## Local development
 
 ### Runtime
 - Node 24 (`.nvmrc`)
@@ -137,7 +137,7 @@ Parallel-worktree isolation:
 - every worktree receives a safe unique `MEILI_INDEX_PREFIX` derived from its normalized workspace name plus `WT_PORT_BASE`
 - both `bookmarks` and `bookmarks_vectors` use that prefix, so separate SQLite states never share Meilisearch documents
 - `pnpm dev:start` defaults the main workspace prefix to `main_`
-- outside this fork's dev launcher, unset `MEILI_INDEX_PREFIX` preserves the original `bookmarks` / `bookmarks_vectors` names
+- an unset `MEILI_INDEX_PREFIX` is a compatibility fallback; manual starts outside `pnpm dev:start` must set an explicit unique prefix for the workspace
 
 ### Direct commands
 
@@ -171,9 +171,9 @@ Optional root `.env` keys:
 
 Every pull restores the full `/data` volume because SQLite rows can reference stored assets. Do not use DB-only pulls or print `.env` secrets. Meilisearch remains derived local state in that workspace's own index namespace.
 
-## Deploy model for this fork
+## Deploy model
 
-This fork uses a **pull-based** personal VPS deploy flow that is separate from the portable guided installer.
+Marka uses a **pull-based** personal VPS deploy flow that is separate from the portable guided installer.
 
 High-level flow:
 - CI passes on `main`
@@ -184,7 +184,7 @@ Important notes:
 - no inbound SSH push-deploy from CI
 - canonical personal VPS compose: `deploy/docker-compose.prod.yml`
 - the guided installer generates its own portable Compose file and does not add Watchtower automatically
-- details for the existing personal VPS live in `docs/fork-setup.md`
+- details for the existing personal VPS live in `docs/operator-setup.md`
 
 ## Quality / maintenance tooling
 
@@ -194,7 +194,7 @@ Standard commands:
 - `pnpm typecheck`
 - `pnpm test`
 
-Additional tooling used in this fork:
+Additional tooling used in this repository:
 - `pnpm knip` - unused files / deps / exports
 - `pnpm doctor` - React health scan via react.doctor
 - `pnpm doctor:staged` - staged-file React scan
@@ -221,18 +221,18 @@ CodeRabbit is currently the only accepted active AI pull-request reviewer. Read
 ## Documentation guidance
 
 This repo's docs are intentionally split into audiences:
-- **public/repo-facing** docs explain Karakeep plus this fork's repo identity
-- **assistant docs** summarize the same fork facts for tooling
+- **public/repo-facing** docs explain Marka and its product identity
+- **assistant docs** summarize the same repository facts for tooling
 - **guided self-host docs** define the portable Docker installer contract
-- **operator docs** capture the existing personal VPS deploy/dev workflow of this fork
+- **operator docs** capture the existing personal VPS deploy/dev workflow of this repository
 
-If you edit fork/dev/deploy facts, keep these aligned:
+If you edit development or deployment facts, keep these aligned:
 - `README.md`
 - `CONTRIBUTING.md`
 - `AGENTS.md`
 - `CLAUDE.md`
 - `GEMINI.md`
-- `docs/fork-setup.md`
+- `docs/operator-setup.md`
 - `docs/docs/02-installation/11-guided-docker-setup.md`
 - relevant pages under `docs/docs/**`
 
@@ -258,8 +258,8 @@ pnpm workers
 
 ## Working style for assistants
 
-- Prefer repo-specific facts over generic upstream assumptions.
+- Prefer repository-specific facts over generic upstream assumptions.
 - Use the guided Docker setup doc for portable fresh-host installation answers.
-- Use `docs/fork-setup.md` for this fork's local-dev and existing personal VPS deployment answers.
-- Treat upstream docs as product context, not as authoritative for this fork's operational workflow.
+- Use `docs/operator-setup.md` for local development and existing personal VPS deployment answers.
+- Treat upstream docs as product context, not as authoritative for Marka's operational workflow.
 - When changing documentation, avoid leaving split or contradictory setup instructions; rewrite for coherence.
diff --git a/CONTEXT.md b/CONTEXT.md
@@ -1,5 +1,11 @@
 # Domain Context
 
+## Product identity
+
+- **Marka**: The public product identity for this repository and its operator-facing surfaces.
+- **Operator-facing name**: A human-visible repository, guide, installer, skill, path, or service label that can change without changing persisted data, protocols, package scopes, or environment-variable contracts.
+- **Compatibility identifier**: A retained Karakeep-era name used by code, packages, environment variables, persisted data, export formats, mobile schemes, or external distribution contracts.
+
 ## List collaboration
 
 - **List owner**: the user who owns a list. Ownership is not a collaborator membership and is never inherited.
@@ -24,4 +30,4 @@
 - Moving a descendant out of a recursively shared subtree removes access that existed only through that inheritance.
 - Explicit direct access on a descendant overrides an inherited role on that descendant. Descendants inherit from the nearest recursive direct grant available on their own ancestor chain.
 - Accessible parents remain navigable in the shared hierarchy. Inaccessible ancestors are not revealed.
-- Public sharing and collaborator sharing can coexist on the same list.
+- Public sharing and collaborator sharing can coexist on the same list.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,33 +2,24 @@
 
 Thanks for taking the time to improve Marka.
 
-This repository is the **Marka fork** of the upstream project, so contribution flow here is a little different from the main project.
+This repository maintains Marka's product, operator workflow, and repository-specific development practices.
 
 ## Which repo should you contribute to?
 
-### Contribute upstream if...
-- your change is generally useful to the main project
-- it is not specific to this fork’s UX/QoL direction
-- it affects the broader community-facing product, install flow, or platform support
-
-Start here:
-- Upstream repo: <https://github.com/karakeep-app/karakeep>
-- Upstream docs: <https://docs.karakeep.app>
-
-### Contribute to this fork if...
-- the change is specific to this fork’s UX, operator workflow, or repo-specific maintenance model
-- it depends on this fork’s pull-based deploy flow or local-dev scripts
-- it intentionally diverges from upstream behavior or presentation
+### Contribute here if...
+- the change improves Marka's UX, operator workflow, or repository-specific maintenance model
+- it depends on Marka's pull-based deploy flow or local-dev scripts
+- it improves a product behavior or presentation maintained in this repository
 
 ## Before you start
 
 - Open an issue or discussion first if the change is large, behavioral, or opinionated.
-- If the change probably belongs upstream, prefer proposing it there instead of here.
-- Read the fork-specific setup guide: [`docs/fork-setup.md`](docs/fork-setup.md)
+- If the change belongs to a different project, propose it there instead of here.
+- Read the operator setup guide: [`docs/operator-setup.md`](docs/operator-setup.md)
 
 ## Local setup
 
-This fork uses:
+Marka uses:
 - Node 24.18.1 (`.nvmrc`; temporarily pinned to avoid the Node 24.19 native-addon cleanup regression)
 - `pnpm@11.2.1` via corepack
 - root `.env` symlinked into `apps/web`, `apps/workers`, and `packages/db`
@@ -50,7 +41,7 @@ pnpm db:migrate
 ```
 
 For the full workflow, detached mode, and production deploy notes, use:
-- [`docs/fork-setup.md`](docs/fork-setup.md)
+- [`docs/operator-setup.md`](docs/operator-setup.md)
 
 ## What to run before opening a PR
 
@@ -80,19 +71,19 @@ Notes:
 
 ### UI / UX changes
 - Include screenshots or a short screen recording.
-- Explain why the change fits this fork specifically.
+- Explain why the change fits Marka specifically.
 - Keep the design language consistent with the current app rather than introducing a second style system.
 
 ### Schema / backend changes
 - Add migrations when needed.
 - Call out any deploy or operator impact clearly.
-- Mention if a change would make upstream sync harder.
+- Mention any compatibility or migration implications.
 
 ### Documentation changes
-If you touch fork, development, or deployment facts, follow the authoritative documentation map:
-- `README.md` provides public fork framing.
+If you touch development or deployment facts, follow the authoritative documentation map:
+- `README.md` provides public product framing.
 - `CONTRIBUTING.md` provides contribution rules.
-- `docs/fork-setup.md` provides fork operation.
+- `docs/operator-setup.md` provides operator setup.
 - `docs/README.md` provides docs-site development.
 - `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` provide concise assistant operations context.
 - Relevant docs-site pages under `docs/docs/**` must stay aligned when their content changes.
@@ -101,10 +92,10 @@ If you touch fork, development, or deployment facts, follow the authoritative do
 
 A good PR for this repo should include:
 - a clear summary of the change
-- why it belongs in this fork
+- why it belongs in Marka
 - screenshots for UI changes
 - commands run for validation
-- any deploy, migration, or sync-with-upstream implications
+- any deploy, migration, or compatibility implications
 
 ## Review expectations
 
@@ -119,6 +110,4 @@ AI review is advisory:
 
 See [`docs/ai-code-review.md`](docs/ai-code-review.md) for the current reviewer policy, rejected-candidate history, permissions ceiling, and future evaluation criteria.
 
-This is a personal fork, so human review cadence is best-effort rather than community-SLA driven.
-
-If you need a guaranteed path to merge for a generally useful change, the upstream Karakeep project is usually the better place to propose it.
+Human review cadence is best-effort rather than community-SLA driven.
diff --git a/PRODUCT.md b/PRODUCT.md
@@ -6,7 +6,7 @@ product
 
 ## Users
 
-A single owner of a self-hosted Karakeep instance (this is a personal fork, not an upstream contribution). The primary user is the operator-owner who lives in the app daily on desktop and mobile. Their context: they come across a link, image, or note and want it **saved in one or two actions, with zero ceremony**, then come back days or weeks later to **find that thing again fast** when they actually need it.
+A single owner of a self-hosted Marka instance. The primary user is the operator-owner who lives in the app daily on desktop and mobile. Their context: they come across a link, image, or note and want it **saved in one or two actions, with zero ceremony**, then come back days or weeks later to **find that thing again fast** when they actually need it.
 
 The job to be done is two-sided and asymmetric:
 - **Capture** (high frequency, must be instant): save a bookmark and move on. AI tagging/summarization happens in the background; the user does not babysit it.
@@ -16,7 +16,7 @@ In-app long-form reading is explicitly **not** the primary workflow. The app is
 
 ## Product Purpose
 
-Karakeep is a self-hostable "bookmark-everything" app: links, notes, images, and PDFs, with background AI tagging and summarization, full-text search, lists, and rule-based organization. This fork serves one person's collection and runs on their own infrastructure.
+Marka is a self-hostable bookmark library for links, notes, images, and PDFs, with background AI tagging and summarization, full-text search, lists, and rule-based organization. It serves one person's collection and runs on their own infrastructure.
 
 Success looks like: saving is so frictionless it becomes reflexive, and retrieval is so reliable the user trusts the app as the place their information lives. The interface should make a large collection feel navigable rather than overwhelming, and make the act of saving feel instant and certain.