docs: establish coherent documentation and assistant context

[absolutepraya]

Goal

Make the repository documentation coherent, current, and useful as durable context for both contributors and coding assistants. The public documentation must explain the product and supported installation paths clearly, while repository assistant files must give accurate, concise operational context without duplicating stale facts.

Problem

Installation, deployment, local-development, and fork-specific facts are currently distributed across README files, the docs site, assistant guidance, samples, and scripts. This makes it easy for a correct change in one place to leave older instructions elsewhere. The repository also has fork-specific split web/worker deployment behavior that must stay distinct from upstream-oriented documentation.

Scope

Establish a documentation source-of-truth map

• Define the intended audience and canonical source for public product docs, contribution guidance, fork operator/deployment guidance, local development, and assistant context.
• Keep README.md, CONTRIBUTING.md, AGENTS.md, CLAUDE.md, GEMINI.md, docs/fork-setup.md, docs/README.md, relevant docs/docs pages, environment samples, and script help aligned where they describe the same behavior.
• State explicitly which upstream documentation remains product context versus which fork documentation is authoritative for this repository.

Refresh factual operational context

• Document the split web and workers images, their version-compatibility requirement, current GHCR tags, Watchtower update model, and the screenshot-first worker profile.
• Document the stable production Compose-project/service convention once selected. Runbooks must target Compose services or labels, not generated container names.
• Reconcile local development, Docker development, production deployment, production-state pull, worker-only configuration, and optional dependencies such as Meilisearch, browser rendering, and inference.
• Ensure examples use placeholders only. Do not add real hostnames, paths, credentials, tokens, email addresses, account details, or other personal/operator-specific data.

Improve assistant context quality

• Keep assistant guidance short, factual, and action-oriented: project layout, canonical commands, test expectations, deployment constraints, documentation ownership, and safety boundaries.
• Remove duplicated or stale implementation detail from assistant files when a canonical document already owns it.
• Add a lightweight documentation-change checklist so cross-cutting changes update every affected public, operator, and assistant surface.

Acceptance criteria

• A documented source-of-truth matrix assigns ownership for product, contribution, operator, local-dev, and assistant documentation.
• All listed documentation and assistant surfaces agree on current fork behavior, commands, image tags, and deployment model.
• Production guidance uses Compose service or label discovery rather than hardcoded generated container names.
• Environment/configuration examples contain only non-sensitive placeholders.
• A repository-wide audit identifies intentional upstream references separately from stale fork references.
• Documentation commands and links are validated, and relevant code/doc checks pass.

Refresh repository previews

• Update the README preview image and any product-facing repository screenshots to the current UI and approved visual identity.

• Record the reproducible source, capture workflow, dimensions, optimization format, and alt text for every checked-in preview asset so a later UI refresh can update them consistently.

• Verify README rendering on GitHub and ensure image paths work from the default branch.

• The README preview image and linked product screenshots reflect the current product UI and approved identity, with documented source and capture instructions.

Repository presentation and discovery metadata

• Audit and update the repository name, description, topics/tags, social preview, README title and headings, badges, and visible repository links to match the current fork identity and positioning.

• Audit page titles, title templates, metadata descriptions, Open Graph/Twitter tags, canonical URLs, structured data, manifest metadata, docs-site title/tagline, and other search/discovery surfaces.

• Keep upstream attribution and compatibility references where intentionally retained, and document why they remain.

• Verify the repository profile and rendered metadata after changes are published.

• Repository name/description/topics, README title, social preview, and all public page/discovery metadata are accurate and mutually consistent.

[absolutepraya]

Completion evidence

The repository/operator documentation coherence work is complete through PRs #43 and #44, with the README follow-up merged in #45:

• README now presents Marka as an independent product and keeps a single Karakeep attribution at the bottom.
• Current repository guidance uses docs/operator-setup.md.
• Installer, operator, local-development, deployment, assistant-context, and active planning references were aligned.
• Marka GHCR paths, canonical domain, operator-facing paths, and live deployment guidance are documented.
• .wt/config.toml prepares isolated dependencies/state without starting a dev server.
• Installer and shared-dev-infrastructure tests pass, and merged PR CI including full E2E tests is green.
• Compatibility-sensitive KARAKEEP_*, package scopes, Compose project/service names, Docker networks, exports, mobile schemes, and persisted identifiers remain explicitly preserved.

Hosted documentation publication remains tracked by #26, and the landing site remains #25.