mirror of https://github.com/aaddrick/claude-desktop-debian.git synced 2026-07-01 06:34:22 +03:00

Files

aaddrick 0c74631f84 docs: add CHANGELOG, RELEASING, SECURITY, docs/index, docs styleguide

Five new top-level docs to round out the project's governance surface,
inspired by a survey of well-organized docs in laravel-commonplace.

- CHANGELOG.md (Keep a Changelog 1.1.0): v2.0.0 onward, grouped by
  REPO_VERSION; +claude upstream retags folded as one-liner inside the
  parent REPO_VERSION section. v2.0.3/.4/.9 reconstructed from git log.
- RELEASING.md: pre-release checklist, tag-and-push recipe, what CI does
  on tag push, mid-release recovery.
- SECURITY.md: private GHSA-based reporting; scope (in/out, what goes
  upstream); response expectations.
- docs/index.md: navigation hub linking BUILDING/CONFIGURATION/
  TROUBLESHOOTING (post-rename paths), decision log, learnings,
  testing, issue-triage, styleguides.
- docs/styleguides/docs_styleguide.md: page anatomy templates
  (setup/troubleshooting/learning/ADR), naming conventions,
  antipatterns, page-size honesty. Tailored to packaging/Electron
  domain; adapted from commonplace's docs_styleguide.

Co-Authored-By: Claude <claude@anthropic.com>

2026-05-24 09:08:55 -04:00

4.1 KiB

Raw Blame History

Documentation

Linux packaging, patching, and operations docs for the Claude Desktop for Debian project. The README is the storefront; this is the manual.

# If you're here because something broke:
claude-desktop --doctor
# Then check troubleshooting.md below.

Installation & building

Building from source — ./build.sh, format flags, the Electron mirror env vars
Configuration — MCP config file locations, env vars, where state lives
Troubleshooting — symptom-keyed fixes, --doctor warning index

Project direction

Decision log — ADR-format record of what we ship and (more importantly) what we won't
Releasing — pre-release checklist, tag recipe, what CI does on tag push
Changelog — v2.0.0 onward, grouped by REPO_VERSION

How the patches work — subsystem deep-dives

Hard-won knowledge from debugging real bugs. Consult before working on the related subsystem; add a new entry when you discover something non-obvious that would save the next contributor (human or AI) significant time.

Patching minified JavaScript — anchor selection, the \w vs $ capture trap, beautified false-negatives, idempotency guards
APT/DNF Worker architecture — Cloudflare Worker + GitHub Releases redirect chain, credential ownership, heartbeat runbook
Nix packaging — NixOS specifics, Electron resource path resolution, testing without NixOS
Linux topbar shim — why the in-app topbar is missing on Linux and the four gates that hide it
Tray rebuild race — KDE SNI re-registration race; the in-place setImage/setContextMenu fast path
Plugin install flow — Anthropic & Partners plugin gate logic and DevTools recipes
Cowork VM daemon — lifecycle, respawn logic, crash diagnosis
MCP double-spawn — why stdio MCPs spawn twice with chat + Code/Agent panels open
Test harness — Electron hooks — why constructor-level BrowserWindow wraps get bypassed by the frame-fix Proxy
Test harness — AX-tree walker — five non-obvious traps in the v7 fingerprint walker

Testing

Testing overview — what we test and how it's organized
Test runbook — running tests locally
Test matrix — what runs on what distro / format
Test automation — CI workflow shape
Quick-entry closeout — the Quick Entry test runner

Operations

Issue triage bot — how the GitHub Actions issue-triage workflow works
Upstream bug reports — bugs we've filed against the upstream Electron app

Style guides

Bash style guide — the project's shell-script conventions (forked from YSAP)
Docs style guide — how to write and organize docs (start here if you're adding a page)

Contributing

CONTRIBUTING.md — what we accept, what goes upstream, AI-attribution policy
CLAUDE.md — instructions for AI coding assistants (and a useful project archaeology read for humans)
AGENTS.md — vendor-neutral mirror of CLAUDE.md for non-Claude AI tools
SECURITY.md — private vulnerability reporting

Cowork-Linux handover (historical)

Cowork-Linux handover — record of the original cowork Linux work, kept for the historical context. Day-to-day cowork docs live in learnings/cowork-vm-daemon.md.

4.1 KiB Raw Blame History