superboard 0.1.0__tar.gz

superboard-0.1.0/.github/workflows/leak-scan.yml

@@ -0,0 +1,31 @@
+# The backstop, not the gate.
+#
+# scripts/hooks/pre-push is what actually prevents a leak — it runs before the
+# commits leave the machine. This runs after they arrive, so it cannot un-publish
+# anything. What it buys is the case the hook cannot cover: a push from a clone
+# where nobody ran install-hooks.sh, a --no-verify, a web edit, a contributor's
+# fork. It is the smoke detector; the hook is not leaving the stove on.
+#
+# It scans the full history of the pushed ref, not just the tip, because that is
+# what a clone can read — hence fetch-depth: 0. A shallow checkout would make the
+# whole job say "clean" for the wrong reason.
+name: leak scan
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  leak-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0        # full history — the surface a clone actually sees
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: working tree
+        run: python3 scripts/leak_scan.py
+      - name: history
+        run: python3 scripts/leak_scan.py --history HEAD

superboard-0.1.0/.github/workflows/macos-smoke.yml

@@ -0,0 +1,75 @@
+name: clean macOS smoke test
+
+on:
+  workflow_dispatch:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  clean-macos:
+    name: macOS / Python ${{ matrix.python-version }}
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build and install the wheel
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m pip install --upgrade pip
+          rm -rf dist
+          python -m pip wheel . --wheel-dir dist
+          test "$(ls dist/superboard-*.whl | wc -l)" -eq 1 || {
+            echo "::error::dist/ holds more than one wheel — cannot tell which is under test"
+            ls -la dist; exit 1
+          }
+          git rev-parse HEAD > dist/BUILD_SHA
+          python -m pip install --force-reinstall dist/superboard-*.whl
+
+      - name: Exercise a clean first start
+        shell: bash
+        env:
+          SB_SMOKE_ROOT: ${{ runner.temp }}
+          SB_SMOKE_LABEL: python-${{ matrix.python-version }}
+        run: |
+          set -euo pipefail
+          SB_SMOKE_PYTHON="$(command -v python)" scripts/smoke-installed.sh
+
+      - name: Record visible end-to-end proof
+        if: matrix.python-version == '3.13'
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m pip install playwright
+          python -m playwright install chromium
+          python scripts/record-installed-e2e.py --output evidence
+
+      - name: Upload visible proof
+        if: always() && matrix.python-version == '3.13'
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-visible-e2e-python-${{ matrix.python-version }}
+          path: evidence/
+          retention-days: 14
+          if-no-files-found: error
+
+      - name: Upload diagnostics on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-smoke-python-${{ matrix.python-version }}
+          path: |
+            ${{ runner.temp }}/superboard-python-${{ matrix.python-version }}.log
+            ${{ runner.temp }}/superboard-collision-python-${{ matrix.python-version }}.log
+            ${{ runner.temp }}/quick-capture-python-${{ matrix.python-version }}.json

superboard-0.1.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,98 @@
+name: publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  pull_request:
+    paths:
+      - ".github/workflows/publish-to-pypi.yml"
+      - "pyproject.toml"
+      - "RELEASES.md"
+      - "scripts/smoke-installed.sh"
+      - "superboard/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.13"
+      - name: Verify tag matches package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        shell: bash
+        run: |
+          set -euo pipefail
+          package_version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "${GITHUB_REF_NAME}" = "v${package_version}"
+      - name: Build distributions
+        run: python -m pip install --upgrade build twine && python -m build
+      - name: Check metadata
+        run: python -m twine check dist/*
+      - name: Install and smoke the exact wheel
+        shell: bash
+        env:
+          SB_SMOKE_ROOT: ${{ runner.temp }}
+          SB_SMOKE_LABEL: release
+        run: |
+          set -euo pipefail
+          python -m pip install --force-reinstall dist/superboard-*.whl
+          SB_SMOKE_PYTHON="$(command -v python)" scripts/smoke-installed.sh
+      - name: Store verified distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build-and-smoke
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/superboard
+    permissions:
+      id-token: write
+    steps:
+      - name: Download verified distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+
+  github-release:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Extract curated release notes
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="${GITHUB_REF_NAME#v}"
+          awk -v heading="## [${version}]" '
+            index($0, heading) == 1 { found=1; next }
+            found && /^## \[/ { exit }
+            found { print }
+          ' RELEASES.md > release-notes.md
+          test -s release-notes.md
+      - name: Create GitHub release after PyPI succeeds
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" --verify-tag --notes-file release-notes.md

superboard-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+# runtime data (never belongs in the repo)
+.superboard/
+sandbox/.data/
+sandbox/inbox/gc-threads/
+sandbox/inbox/gc-receipts/
+sandbox/inbox/board-archive.md
+journal/
+usage-log.jsonl
+git-anchor.json
+killed-runs.jsonl
+killed/
+thread-search.sqlite
+board.config.json
+dist/
+# resolver artefact of `uv run --with …` during testing, not a project lock
+uv.lock
+.testrig/
+# browser profile the UI smoke test creates next to the package
+board-smoke/
+# private leak-scan vocabulary (symlink into a private repo) — never publish
+.leakpatterns

superboard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Meindl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

superboard-0.1.0/PITCH.md

@@ -0,0 +1,9 @@
+# Where this goes — the long version
+
+Tuesday, 8:40. You sit down to three items — not forty. One is a two-option sheet with a recommendation and the single number that actually moves the decision. One is a draft parked at the exact point where your edits carry the most weight. One is a raw idea, deliberately untouched, because the system has learned that's the kind you want to shape yourself. Next to them, a short reading: two things that moved overnight that you'd genuinely want to see. Everything else was researched, built, filed, or consciously not started — each weighed in the open against priorities you set.
+
+This didn't take years of working together. It took weeks. Coaching a great hire into this takes months; here the loop runs on days. There is a real onboarding period — it asks too much at first, you correct constantly, and the correcting is the investment. Then the questions change character: "Before I finish this — you killed a similar idea in March because it competed with the launch for your attention. Still true?"
+
+And you can always see what it knows. Everything it has learned about working with you sits in plain files you can open and amend in a text editor. When a better model ships, you point it at your folder. By afternoon it works with you like before, but sharper. Flow doesn't reset.
+
+Today, Superboard is a board. Step one of exactly this.

superboard-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: superboard
+Version: 0.1.0
+Summary: A personal task board where every to-do is a standing conversation thread with your agent.
+Project-URL: Homepage, https://github.com/bmeindl/superboard
+Project-URL: Documentation, https://github.com/bmeindl/superboard#readme
+Project-URL: Issues, https://github.com/bmeindl/superboard/issues
+Project-URL: Source, https://github.com/bmeindl/superboard
+Author: Benjamin Meindl
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,claude,kanban,personal-task-host,todo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Superboard
+
+**A local to-do board where every card can stay manual or become a standing
+conversation with a coding agent.** Add ordinary work first; delegate research,
+writing or changes when that helps. The underlying state stays in plain files
+you own.
+
+[![leak scan](https://github.com/bmeindl/superboard/actions/workflows/leak-scan.yml/badge.svg?branch=main)](https://github.com/bmeindl/superboard/actions/workflows/leak-scan.yml)
+
+![A fresh Superboard workspace with onboarding separate from ordinary to-dos](https://raw.githubusercontent.com/bmeindl/superboard/v0.1.0/docs/assets/superboard-hero.png)
+
+```sh
+uvx superboard ~/Superboard
+# then open http://localhost:47822
+```
+
+Already use Claude Code? Give it the whole setup job:
+
+> Use <https://github.com/bmeindl/superboard> as the Superboard package I want.
+> Read its README, explain what you will run, set it up in `~/Superboard`, start
+> it, and open the local board for me. Do not clone the source into my workspace.
+
+Claude Code still uses its existing host permissions and may ask before installing
+`uv` or opening an application. The explicit terminal command above remains the
+portable fallback.
+
+## The one-minute version
+
+1. Open the board. A fresh workspace separates **Getting started** from the empty
+   **My to-dos** area where normal work belongs.
+2. Open **1 · Start here · Meet Superboard** and press **▶ Agent**. It opens the
+   local introduction when the runner can access your desktop; otherwise it returns
+   the local link. It answers questions in that card and tells you when to mark it done.
+3. Use **2 · Set up this workspace**, then **3 · Add your first real to-do**.
+   The agent adapts the foundation and puts one genuine card under My to-dos.
+4. The remaining cards each name one outcome—agent/model setup, Cockpit, email
+   digest, one routine, Off Duty, night rest or later thread learning—so you can
+   complete or skip them independently.
+5. Add more work whenever. `Enter` creates a manual card; `Cmd/Ctrl+Enter` creates it and
+   starts the agent.
+6. Finish onboarding. The final card archives the setup threads and removes the
+   Getting started category.
+
+This is not a five-minute setup, and it does not pretend to be. A board becomes
+genuinely useful over weeks, as your own threads accumulate.
+
+There is no settings maze. Topics, actions, rituals, context, and skills are
+workspace files. Ask the agent to change them; inspect the diff whenever you
+want. Optional procedural skills can be copied from a separate catalogue one at
+a time, previewed first, and then customized locally.
+
+## What you need
+
+- Python 3.10+ and `uv`/`uvx`. The release gates cover macOS and Ubuntu; Windows
+  has not been verified and is not supported in this alpha.
+- Claude Code installed and authenticated for the supported default runner.
+- Codex is an experimental macOS runner and uses the CLI bundled with ChatGPT.
+  OpenCode is not a supported runner in `0.1.0`.
+- Provider usage: Superboard does not include model access or tokens.
+
+The board still opens without an agent CLI, but hand-offs cannot run — and it
+says so: the first screen carries the reason and the ▶ Agent buttons are marked
+rather than silently inert.
+
+## What an agent run can do
+
+`▶ Agent` starts the selected CLI in auto mode. The run inherits that CLI's host
+access and configured MCP/provider setup; when the task requires it, the agent can
+edit or commit inside the workspace and may propose machine-wide or outside-workspace
+actions. Superboard does not wrap the CLI in a second approval system. Tell the agent
+what is off-limits, ask it to change its local operating rules, or ask for exact
+terminal handoff commands when an interactive step is needed. The files and git diff
+remain the review surface.
+
+## Why local files?
+
+Superboard has no cloud account, database, or sync service. The board, context,
+and learned working rules stay inspectable and portable inside your workspace.
+Changing agent providers does not mean abandoning what the workspace learned.
+
+Each `▶ Agent` starts a fresh CLI process. Continuity comes from a resumable
+provider session plus the durable board thread — not from a hidden Superboard
+memory. A warm provider cache may reduce repeated tokens; a cold cache never
+loses work.
+
+## How it works
+
+Superboard is the piece that holds your work and coordinates the agents doing it — a personal task host. The **board** is the visible surface — columns, cards, one glance. Each **card** is a task with its own standing thread: the full conversation between you and the agent working it, persistent across weeks. A **runner** executes — it picks up cards you've handed off, works headlessly, and reports back into the thread: results, or a short decision sheet when only you can decide. Underneath: plain local markdown files. No database, no account, no sync. The agent brings the intelligence; the files keep it honest.
+
+## The first weeks
+
+Superboard doesn't promise one-minute setup. It promises an honest onboarding — the kind you'd give a strong new hire. Week one, it asks too much: it doesn't know your projects, your people, or which decisions are yours alone. You correct it constantly, and the correcting is the investment — every correction lands in plain files it reads next time, and you can open any of them to see exactly what it thinks it knows. A few weeks in, the questions change character: less "what is this?", more "you killed a similar idea in March because it competed for your attention — still true?" And it compounds with what you already have: Superboard runs on top of your existing agent setup, and the more you bring — skills, context, working habits — the faster it gets good. Starting from zero works too; it just makes the first weeks matter more. Tools that promise instant magic tend to plateau fast. Superboard starts slower — and keeps compounding.
+
+## Agentic first — it grows, and you grow it
+
+The mechanics work on day one: board, runner, standing threads, decision sheets, a working skill set — extracted from a system used daily for months. The personalization is what takes weeks. And nothing about it is finished, by design: there is no feature backlog between you and the tool — when you want the cards to work differently, you don't file a request, you tell your agent to rebuild them. The whole system is plain files and readable code, small enough for an agent to navigate and change, with every change reviewable. From the first week it grows toward you: your skills, your rules, what it has learned about how you decide. Every install grows toward its owner — that divergence is the point, not a side effect. And it flows both ways: when your setup grows something good — a skill, a routine, a sharper way of asking — it's built to flow back through ordinary open-source contribution and become part of everyone's next start. That's open source applied to a tool whose job is to learn.
+
+## Where this goes
+
+Today, Superboard is a board. The direction is a working morning that starts with three prepared items instead of forty open loops — everything else researched, built, filed, or consciously not started while you were away, each weighed in the open against priorities you set. Questions that get sharper the longer you work together. And because everything it learns lives in inspectable files, changing models doesn't have to mean starting over. That's the target narrative, told honestly as direction — the full version is in [PITCH.md](https://github.com/bmeindl/superboard/blob/v0.1.0/PITCH.md). This board is step one of exactly it.
+
+## Start here, then ask the agent
+
+The board and its onboarding cards are the primary product documentation. The
+README deliberately stops at orientation; users should not need to study a
+manual before doing useful work.
+
+- [Using Superboard](https://github.com/bmeindl/superboard/blob/v0.1.0/docs/USING-SUPERBOARD.md) — installation, workspace files,
+  onboarding behavior, customization, and restart rules.
+- [Development and test rigs](https://github.com/bmeindl/superboard/blob/v0.1.0/docs/DEVELOPMENT.md) — sandbox, fresh-wheel test,
+  and privacy gates.
+- [Architecture](https://github.com/bmeindl/superboard/blob/v0.1.0/superboard/ARCHITEKTUR.md) — contracts and trust boundaries for
+  agents and contributors.
+- [Product direction](https://github.com/bmeindl/superboard/blob/v0.1.0/PITCH.md) · [Support posture](https://github.com/bmeindl/superboard/blob/v0.1.0/SUPPORT.md)
+
+Superboard is alpha-stage personal tooling, not a hosted multi-user project
+manager or a supported service. The point is a small, understandable frame that
+your own agent and workspace can grow into.
+
+## License
+
+MIT — see [LICENSE](https://github.com/bmeindl/superboard/blob/v0.1.0/LICENSE).

superboard-0.1.0/README.md

@@ -0,0 +1,122 @@
+# Superboard
+
+**A local to-do board where every card can stay manual or become a standing
+conversation with a coding agent.** Add ordinary work first; delegate research,
+writing or changes when that helps. The underlying state stays in plain files
+you own.
+
+[![leak scan](https://github.com/bmeindl/superboard/actions/workflows/leak-scan.yml/badge.svg?branch=main)](https://github.com/bmeindl/superboard/actions/workflows/leak-scan.yml)
+
+![A fresh Superboard workspace with onboarding separate from ordinary to-dos](https://raw.githubusercontent.com/bmeindl/superboard/v0.1.0/docs/assets/superboard-hero.png)
+
+```sh
+uvx superboard ~/Superboard
+# then open http://localhost:47822
+```
+
+Already use Claude Code? Give it the whole setup job:
+
+> Use <https://github.com/bmeindl/superboard> as the Superboard package I want.
+> Read its README, explain what you will run, set it up in `~/Superboard`, start
+> it, and open the local board for me. Do not clone the source into my workspace.
+
+Claude Code still uses its existing host permissions and may ask before installing
+`uv` or opening an application. The explicit terminal command above remains the
+portable fallback.
+
+## The one-minute version
+
+1. Open the board. A fresh workspace separates **Getting started** from the empty
+   **My to-dos** area where normal work belongs.
+2. Open **1 · Start here · Meet Superboard** and press **▶ Agent**. It opens the
+   local introduction when the runner can access your desktop; otherwise it returns
+   the local link. It answers questions in that card and tells you when to mark it done.
+3. Use **2 · Set up this workspace**, then **3 · Add your first real to-do**.
+   The agent adapts the foundation and puts one genuine card under My to-dos.
+4. The remaining cards each name one outcome—agent/model setup, Cockpit, email
+   digest, one routine, Off Duty, night rest or later thread learning—so you can
+   complete or skip them independently.
+5. Add more work whenever. `Enter` creates a manual card; `Cmd/Ctrl+Enter` creates it and
+   starts the agent.
+6. Finish onboarding. The final card archives the setup threads and removes the
+   Getting started category.
+
+This is not a five-minute setup, and it does not pretend to be. A board becomes
+genuinely useful over weeks, as your own threads accumulate.
+
+There is no settings maze. Topics, actions, rituals, context, and skills are
+workspace files. Ask the agent to change them; inspect the diff whenever you
+want. Optional procedural skills can be copied from a separate catalogue one at
+a time, previewed first, and then customized locally.
+
+## What you need
+
+- Python 3.10+ and `uv`/`uvx`. The release gates cover macOS and Ubuntu; Windows
+  has not been verified and is not supported in this alpha.
+- Claude Code installed and authenticated for the supported default runner.
+- Codex is an experimental macOS runner and uses the CLI bundled with ChatGPT.
+  OpenCode is not a supported runner in `0.1.0`.
+- Provider usage: Superboard does not include model access or tokens.
+
+The board still opens without an agent CLI, but hand-offs cannot run — and it
+says so: the first screen carries the reason and the ▶ Agent buttons are marked
+rather than silently inert.
+
+## What an agent run can do
+
+`▶ Agent` starts the selected CLI in auto mode. The run inherits that CLI's host
+access and configured MCP/provider setup; when the task requires it, the agent can
+edit or commit inside the workspace and may propose machine-wide or outside-workspace
+actions. Superboard does not wrap the CLI in a second approval system. Tell the agent
+what is off-limits, ask it to change its local operating rules, or ask for exact
+terminal handoff commands when an interactive step is needed. The files and git diff
+remain the review surface.
+
+## Why local files?
+
+Superboard has no cloud account, database, or sync service. The board, context,
+and learned working rules stay inspectable and portable inside your workspace.
+Changing agent providers does not mean abandoning what the workspace learned.
+
+Each `▶ Agent` starts a fresh CLI process. Continuity comes from a resumable
+provider session plus the durable board thread — not from a hidden Superboard
+memory. A warm provider cache may reduce repeated tokens; a cold cache never
+loses work.
+
+## How it works
+
+Superboard is the piece that holds your work and coordinates the agents doing it — a personal task host. The **board** is the visible surface — columns, cards, one glance. Each **card** is a task with its own standing thread: the full conversation between you and the agent working it, persistent across weeks. A **runner** executes — it picks up cards you've handed off, works headlessly, and reports back into the thread: results, or a short decision sheet when only you can decide. Underneath: plain local markdown files. No database, no account, no sync. The agent brings the intelligence; the files keep it honest.
+
+## The first weeks
+
+Superboard doesn't promise one-minute setup. It promises an honest onboarding — the kind you'd give a strong new hire. Week one, it asks too much: it doesn't know your projects, your people, or which decisions are yours alone. You correct it constantly, and the correcting is the investment — every correction lands in plain files it reads next time, and you can open any of them to see exactly what it thinks it knows. A few weeks in, the questions change character: less "what is this?", more "you killed a similar idea in March because it competed for your attention — still true?" And it compounds with what you already have: Superboard runs on top of your existing agent setup, and the more you bring — skills, context, working habits — the faster it gets good. Starting from zero works too; it just makes the first weeks matter more. Tools that promise instant magic tend to plateau fast. Superboard starts slower — and keeps compounding.
+
+## Agentic first — it grows, and you grow it
+
+The mechanics work on day one: board, runner, standing threads, decision sheets, a working skill set — extracted from a system used daily for months. The personalization is what takes weeks. And nothing about it is finished, by design: there is no feature backlog between you and the tool — when you want the cards to work differently, you don't file a request, you tell your agent to rebuild them. The whole system is plain files and readable code, small enough for an agent to navigate and change, with every change reviewable. From the first week it grows toward you: your skills, your rules, what it has learned about how you decide. Every install grows toward its owner — that divergence is the point, not a side effect. And it flows both ways: when your setup grows something good — a skill, a routine, a sharper way of asking — it's built to flow back through ordinary open-source contribution and become part of everyone's next start. That's open source applied to a tool whose job is to learn.
+
+## Where this goes
+
+Today, Superboard is a board. The direction is a working morning that starts with three prepared items instead of forty open loops — everything else researched, built, filed, or consciously not started while you were away, each weighed in the open against priorities you set. Questions that get sharper the longer you work together. And because everything it learns lives in inspectable files, changing models doesn't have to mean starting over. That's the target narrative, told honestly as direction — the full version is in [PITCH.md](https://github.com/bmeindl/superboard/blob/v0.1.0/PITCH.md). This board is step one of exactly it.
+
+## Start here, then ask the agent
+
+The board and its onboarding cards are the primary product documentation. The
+README deliberately stops at orientation; users should not need to study a
+manual before doing useful work.
+
+- [Using Superboard](https://github.com/bmeindl/superboard/blob/v0.1.0/docs/USING-SUPERBOARD.md) — installation, workspace files,
+  onboarding behavior, customization, and restart rules.
+- [Development and test rigs](https://github.com/bmeindl/superboard/blob/v0.1.0/docs/DEVELOPMENT.md) — sandbox, fresh-wheel test,
+  and privacy gates.
+- [Architecture](https://github.com/bmeindl/superboard/blob/v0.1.0/superboard/ARCHITEKTUR.md) — contracts and trust boundaries for
+  agents and contributors.
+- [Product direction](https://github.com/bmeindl/superboard/blob/v0.1.0/PITCH.md) · [Support posture](https://github.com/bmeindl/superboard/blob/v0.1.0/SUPPORT.md)
+
+Superboard is alpha-stage personal tooling, not a hosted multi-user project
+manager or a supported service. The point is a small, understandable frame that
+your own agent and workspace can grow into.
+
+## License
+
+MIT — see [LICENSE](https://github.com/bmeindl/superboard/blob/v0.1.0/LICENSE).

superboard-0.1.0/RELEASES.md

@@ -0,0 +1,21 @@
+# Releases
+
+Public version history of Superboard. The public number (`pyproject.toml`, what PyPI
+and `uvx` show) moves only at deliberate releases and follows the usual reading:
+patch = fixes, minor = something new, major = something you should read about
+before upgrading. `Build` names the internal board stand that ships inside a release
+— that number counts every change by size and is not a stability promise.
+`CHANGELOG.md` inside the package is that internal build history.
+
+## [0.1.0] — 2026-08-26 · first public alpha
+
+- A local Now / Next / Backlog board where an ordinary to-do can stay manual or
+  become a standing conversation with an agent.
+- Thirteen concrete onboarding cards sit separately from an empty My to-dos area;
+  the agent-led introduction, first genuine task, runner setup, help, Cockpit
+  actions, and optional routines each have one clear outcome.
+- Claude Code is the supported default runner; Codex on macOS is experimental.
+- Plain Markdown and JSON remain the source of truth—no hosted account, database,
+  or bundled model access.
+- Release gates cover the exact wheel, macOS and Ubuntu smoke tests, a real-agent
+  confirmation journey, and private-vocabulary leak scans.

superboard-0.1.0/RELEASING.md

@@ -0,0 +1,87 @@
+# Releasing Superboard
+
+**This is guidance, not law — a living document.** It collects what we currently
+think a good release looks like: the technical steps and the product checks around
+them. Read it before a release, pick what applies with judgment, skip what does not
+(say so in the release notes' working thread), and — the one real rule — **leave it
+better than you found it**: every release that teaches something edits this file in
+the same commit. The owner takes the calls marked **OWNER**.
+
+Why guidance: a public release is a *promise*, not a version bump. The internal board
+counts every change by size (`Build 6.x`, see `superboard/CHANGELOG.md`); the public
+number (`pyproject.toml`, `RELEASES.md`) moves only when we consciously say "this is
+what a stranger gets now".
+
+## 0 · Decide that a release is due
+
+- **OWNER** picks the number and the step: patch = fixes only · minor = something new
+  a user notices · major = something to read before upgrading.
+- Write down, in one sentence, what this release is *for* — it becomes the first line
+  of the release notes.
+
+## 1 · Bring the public projection up to date
+
+- From the origin board, run its port status (`port_to_superboard.py`): classify every
+  reported file as launch-relevant, intentionally divergent, superseded, or deferred.
+  Port launch-relevant changes and record the rest; a raw count is not a release gate.
+- Compare both build numbers before `sync-version`. Run it only when the origin is
+  actually ahead; never use it to downgrade a candidate with independent fixes.
+- Run `scripts/leak_scan.py --history` on purpose; the hooks are a backstop.
+
+## 2 · Test what a stranger actually gets
+
+- Fresh install from a clean environment using the *built artifact*, not the source
+  tree: `scripts/testrig.sh fresh`.
+- Installed smoke: `scripts/smoke-installed.sh`, plus green macOS smoke on the release
+  commit.
+- **E2E by hand:** empty workspace → first run → first item → agent reply →
+  thread → archive. `scripts/record-installed-e2e.py` records the proof.
+- Every supported OS/Python claimed in the README gets at least the smoke; remove
+  untested claims.
+
+## 3 · Product surface — does the outside still match the inside?
+
+- Read the README top to bottom as a stranger and run every command verbatim.
+- Compare screenshots and demos with the E2E proof. Changed UI means re-recording.
+- Recheck `PITCH.md`, `SUPPORT.md`, package metadata, and the sandbox.
+
+## 4 · Write the release
+
+- From the origin board: `port_to_superboard.py release <x.y.z>` sets the public
+  version and prepares the `RELEASES.md` entry.
+- Curate the notes into 3–8 user-facing lines; delete the raw internal headings.
+- **OWNER** reads the notes and README diff. This is the go/no-go.
+
+## 5 · Publish
+
+- Before the first release, create the GitHub `pypi` environment with required manual
+  approval and register a PyPI pending publisher for the GitHub owner reported by
+  `gh repo view --json nameWithOwner`, repository `superboard`, workflow
+  `publish-to-pypi.yml`, environment `pypi`.
+- Commit (`chore(release): v<x.y.z>`), tag `v<x.y.z>`, and push only after the explicit
+  go. Never push directly to main.
+- Use a public no-reply identity for commit and annotated-tag metadata. The history
+  leak gate scans commit objects as well as blobs; inspect its author/committer output.
+- The tag workflow builds, checks, installs, smokes, and publishes the same artifact via
+  Trusted Publishing. Never use a local PyPI token.
+- Verify from outside: clean environment, `uvx superboard --version`, first run,
+  PyPI page, GitHub release page, README images and links.
+
+## 6 · After
+
+- Announce through the launch channels selected for this release.
+- Watch the first days for issues, install failures, and CI failures.
+- Put anything learned about the ritual back into this file.
+
+## Hard lines
+
+No release with an unresolved launch-relevant port item, a red installed smoke, or a
+README claim nobody verified this round.
+
+## Changelog of this document
+
+- 2026-08-25 · first version; deliberately expected to evolve after the first release.
+- 2026-08-26 · added the concrete pending-publisher identity, approval environment,
+  and same-artifact build/smoke/publish contract.
+- 2026-08-26 · added commit-metadata privacy and curated GitHub release notes after
+  the final launch challenge found that clean blobs were not the whole public surface.

superboard-0.1.0/SECURITY.md

@@ -0,0 +1,14 @@
+# Security policy
+
+Superboard is an alpha desktop tool that runs local agent CLIs with the permissions
+of the account and machine that start it. Review the workspace instructions before
+using auto mode, and do not put secrets in `board.md` or a public issue.
+
+## Reporting a vulnerability
+
+Please use the repository's **Security → Advisories → Report a vulnerability** flow on GitHub.
+Include the affected version, reproduction steps, and the impact. Do not open a public
+issue until the report has been assessed.
+
+Security reports for the current `0.1.x` alpha line are accepted. Fix timelines depend
+on severity; there is no separate long-term-support branch yet.