titan-ron · Sep 24, 2026 · Sep 24, 2026 · Sep 24, 2026 · Sep 24, 2026 · Sep 24, 2026
@@ -0,0 +1,54 @@
+name: Report a problem
+description: Something in Cockpit is broken, stuck or wrong.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time. **Settings › About › Report a problem** opens this form
+        with the version fields already filled in.
+        Sessions that are missing or show the wrong title, branch or transcript have
+        [their own form](https://github.com/tashtit/cockpit/issues/new?template=sessions.yml).
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you saw, and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: How to make it happen again
+      description: The steps, if you know them. "It happened once" is useful too.
+      placeholder: |
+        1. Open a Codex session
+        2. Send a message while the agent is working
+        3. …
+  - type: input
+    id: version
+    attributes:
+      label: Cockpit version
+      description: Settings › About shows it.
+      placeholder: "0.31.1"
+    validations:
+      required: true
+  - type: input
+    id: macos
+    attributes:
+      label: macOS
+      placeholder: "26.0 (arm64)"
+  - type: textarea
+    id: agents
+    attributes:
+      label: Agent CLIs
+      description: Which agent CLIs you have, and their versions.
+      placeholder: |
+        Claude Code: 2.1.236 (Homebrew cask)
+        Codex: 0.154.0 (npm)
+        Copilot: not installed
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else
+      description: Screenshots, or the error text. Please leave out anything private — this issue is public.
@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Ask a question
+    url: https://github.com/tashtit/cockpit/discussions/categories/q-a
+    about: How do I…? Does Cockpit…? Ask in Discussions.
+  - name: Show what you use it for
+    url: https://github.com/tashtit/cockpit/discussions/categories/show-and-tell
+    about: Your setup, your workflow, a screenshot — we read every one.
+  - name: Report a security vulnerability
+    url: https://github.com/tashtit/cockpit/security/advisories/new
+    about: Privately, please — not in a public issue.
@@ -0,0 +1,16 @@
+name: Suggest an idea
+description: Something Cockpit could do, or do better.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What you are trying to do
+      description: The situation, and what gets in the way today. This matters more than the solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would help
+      description: How you imagine it working, if you have an idea.
@@ -0,0 +1,53 @@
+name: Sessions missing or wrong
+description: A session doesn't show up, or shows the wrong title, repo, branch or transcript.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Each agent writes its own session log format, and the formats change between CLI
+        releases — so the agent and its version are what tell us where to look.
+        Please don't attach a session log: it holds your conversation. Describe what is
+        wrong and we'll ask for anything specific.
+  - type: dropdown
+    id: agent
+    attributes:
+      label: Agent
+      options:
+        - Claude Code
+        - Codex
+        - Copilot CLI
+        - Another agent over ACP
+    validations:
+      required: true
+  - type: textarea
+    id: what-is-wrong
+    attributes:
+      label: What is missing or wrong
+      description: For example "sessions from the last two days don't appear", or "the branch shows main but the session ran on a worktree branch".
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Cockpit version
+      description: Settings › About shows it.
+      placeholder: "0.31.1"
+    validations:
+      required: true
+  - type: input
+    id: macos
+    attributes:
+      label: macOS
+      placeholder: "26.0 (arm64)"
+  - type: textarea
+    id: agents
+    attributes:
+      label: Agent CLIs
+      description: Which agent CLIs you have, and their versions.
+      placeholder: |
+        Claude Code: 2.1.236 (Homebrew cask)
+        Codex: 0.154.0 (npm)
+        Copilot: not installed
+    validations:
+      required: true
@@ -0,0 +1,10 @@
+## What and why
+
+<!-- What changes for someone using Cockpit, and why. Link the issue if there is one. -->
+
+## How it was checked
+
+- [ ] `npm run typecheck`
+- [ ] `npm test`
+- [ ] Seen in the running app (`npm run dev`), for anything a person sees
+- [ ] `docs/guide/` updated, for anything that changes what a person sees or does
@@ -0,0 +1,60 @@
+name: 'Docs'
+
+# The user guide in docs/, published to GitHub Pages (https://tashtit.github.io/cockpit/).
+# Pull requests that touch it only build it — VitePress fails the build on a dead link,
+# which is the one thing about the guide a machine can check — and main deploys it.
+# No analytics and no cookies: the site is the built VitePress output and nothing else.
+on:
+  workflow_dispatch:
+  pull_request:
+    paths: ['docs/**', 'package-lock.json', '.github/workflows/docs.yml']
+  push:
+    branches: [main]
+    paths: ['docs/**', 'package-lock.json', '.github/workflows/docs.yml']
+
+# One deployment at a time: a deploy in progress finishes, the newest queued one follows.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: 'read' # for actions/checkout
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7.0.1
+        with: { persist-credentials: false }
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7.0.0
+        with: { node-version-file: '.nvmrc', cache: 'npm' }
+
+      - name: Install
+        run: npm ci
+
+      - name: 📚 Build the guide
+        run: npm run docs:build
+
+      - name: Upload the site
+        if: ${{ github.event_name != 'pull_request' }}
+        uses: actions/upload-pages-artifact@v5.0.0
+        with: { path: docs/.vitepress/dist }
+
+  deploy:
+    if: ${{ github.event_name != 'pull_request' }}
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: 'write' # for actions/deploy-pages
+      id-token: 'write' # deploy-pages proves which run the site came from
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - name: 🚀 Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v5.0.1
@@ -11,6 +11,7 @@ coverage/
 
 # VitePress (build output is covered by dist/)
 docs/.vitepress/cache/
+docs/.vitepress/dist/
 
 # Editor / local tooling
 .idea/

@@ -44,7 +44,7 @@
           { "path": "dist/*.blockmap" },
           { "path": "dist/latest-mac.yml" }
         ],
-        "releaseBodyTemplate": "<%= nextRelease.notes %>\n\n## Install\n\nCockpit isn't signed with an Apple Developer ID yet, so macOS blocks the first launch. Once only:\n\n1. Download the `.dmg` for your Mac below — `arm64` for Apple silicon, `x64` for Intel — and drag Cockpit into Applications.\n2. Open Cockpit. When macOS says it can't verify the app, click **Done**.\n3. In System Settings › Privacy & Security, click **Open Anyway** — or in Terminal: `xattr -d com.apple.quarantine /Applications/Cockpit.app`\n\nAfter that, Cockpit updates itself.\n\n[Full install guide](https://github.com/tashtit/cockpit#install) · Verify a download: `gh attestation verify <file> --owner tashtit`\n",
+        "releaseBodyTemplate": "<%= nextRelease.notes %>\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/tashtit/cockpit/main/scripts/install.sh | sh\n```\n\nor `brew install --cask tashtit/tap/cockpit`. Either checks the download against the SHA-256 digest GitHub lists for it and opens without a trip to Privacy & Security. After that, Cockpit updates itself.\n\nPrefer the `.dmg`? Pick yours below — `arm64` for Apple silicon, `x64` for Intel. It isn't signed with an Apple Developer ID yet, so macOS blocks its first launch once: click **Done**, then **Open Anyway** in System Settings › Privacy & Security (or `xattr -d com.apple.quarantine /Applications/Cockpit.app`).\n\n[Install guide](https://tashtit.github.io/cockpit/guide/getting-started) · [Report a problem](https://github.com/tashtit/cockpit/issues/new?template=bug.yml) · Verify a download: `gh attestation verify <file> --owner tashtit`\n",
         "successComment": false,
         "failComment": false,
         "failTitle": false,

@@ -17,6 +17,7 @@ This file provides guidance to AI coding agents (Claude Code, Codex, GitHub Copi
 - `npm run package` — macOS disk images + zips into `dist/` via electron-builder (unsigned without Apple credentials; version `0.0.0` outside a release)
 - `npm run test:packaged` — Playwright smoke test against the `.app` from `npm run package` (`tests/e2e/packaged.spec.ts`; opt-in, uses the real userData dir)
 - `npm run docs:dev` — the user guide (VitePress, `docs/`) with hot reload; `docs:build` / `docs:preview` for the built site
+- `npm run stats` — adoption and outside feedback from read-only `gh api` calls (no telemetry): traffic, stars, release downloads by meaning (dmg = new install, zip = update, `latest-mac.yml` = update check → active-install estimate), non-team issues/comments/discussions. Folds GitHub's 14-day traffic and one counter snapshot per UTC day into `~/.local/share/cockpit-stats/history.json` (`--history <file>`, `--json`); logic in `scripts/stats-core.mts`
 - `npm run ui:tour` — builds, then screenshots every view and state against a hermetic fixture world (`scripts/ui-tour/`): desktop, an ordinary 900×700 window, the 560×420 floor and 200% zoom, sessions actually flying and landing (stub agent CLIs stream slowly), and a first launch. Writes `test-results/ui-tour/` with an `index.html` contact sheet; a shot it can't reach is marked missing and fails the run. `-- --only chat,settings` narrows it, `-- --no-live` skips the ~40s of live turns
 
 Both `npm run typecheck` and `npm test` must pass before delivering.
@@ -180,9 +181,11 @@ full-screen specs; don't set it unasked.
 
 ## Documentation
 
-The user guide is a VitePress site in `docs/` (`docs/guide/`, one page per feature). It is
-**deliberately not deployed** — there is no Pages workflow and none is wanted yet. It is read
-locally with `npm run docs:dev`, so treat it as part of the repo rather than as a published site.
+The user guide is a VitePress site in `docs/` (`docs/guide/`, one page per feature), published
+to GitHub Pages at https://tashtit.github.io/cockpit/ by `.github/workflows/docs.yml` on every
+push to `main` that touches it; pull requests only build it, which fails on a dead link. It has
+no analytics and none is wanted. `npm run docs:dev` serves it under the same `/cockpit/` base —
+a `head` tag's URL must carry that base itself, since only themeConfig and markdown links get it.
 VitePress 1.x pins its own `vite` 5 (and `esbuild` 0.21), both past their security fixes, so
 `overrides` in `package.json` hands it the root `vite` instead — drop the override once VitePress 2
 is stable. Pages are compiled as Vue templates: a bare `<placeholder>` outside a code span is an

@@ -0,0 +1,130 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement privately: use
+**Report content** from the **…** menu on the issue, pull request, discussion or
+comment concerned, which reaches the maintainers of this repository, or contact a
+maintainer (@titan-ron, @amitbreuer, @matansocher) through their GitHub profile.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.