attache 0.0.1__tar.gz

attache-0.0.1/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.png binary
+*.woff2 binary

attache-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  # release.yml calls this, so a tag is gated by exactly the checks main is gated by.
+  workflow_call:
+
+permissions:
+  contents: read
+
+# A newer push makes an older run's answer irrelevant. Tags are exempt: cancelling a release
+# mid-flight is never what anyone wants.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+env:
+  UV_LOCKED: "1"  # a stale uv.lock fails CI instead of being re-resolved
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+      # Pinned to the locked version, so a new ruff release can't fail unrelated pull requests.
+      - name: Ruff lint
+        run: uvx ruff@0.17.1 check .
+      - name: Ruff format check
+        run: uvx ruff@0.17.1 format --check .
+
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run tests (includes the core size budget)
+        run: uv run pytest
+
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Smoke-test the built wheel
+        run: |
+          wheel=$(ls dist/*.whl)
+          uvx --isolated --from "$wheel" attache --help
+          uvx --isolated --from "$wheel" attache init --home "$RUNNER_TEMP/home" --name CI
+          test -f "$RUNNER_TEMP/home/skills/todos/SKILL.md"
+          test -f "$RUNNER_TEMP/home/artifacts/home.html"
+          uv run --isolated --no-project --with "$wheel" python -c "import attache.app, attache.web"

attache-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+name: Docs
+
+# Build the Zensical documentation site and publish it to GitHub Pages.
+# Pull requests build it too, without deploying, so a broken page shows up in review.
+#
+# One-time setup: Settings -> Pages -> Build and deployment -> Source = GitHub Actions.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "zensical.toml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "zensical.toml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# Least privilege: build only reads the repo; deploy alone gets the Pages and OIDC scopes.
+permissions:
+  contents: read
+
+# One Pages deploy at a time, and never cancel one halfway. Pull request builds get their own
+# group, so they neither wait for nor cancel a deploy.
+concurrency:
+  group: ${{ github.event_name == 'pull_request' && format('docs-{0}', github.ref) || 'pages' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  UV_LOCKED: "1"  # a stale uv.lock fails the build instead of being re-resolved
+
+# Actions are pinned to commit SHAs: the deploy job can write to the Pages site.
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - name: Configure Pages
+        if: github.event_name != 'pull_request'
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+      # --strict fails the build on a link to a missing page or anchor.
+      - name: Build the docs site
+        run: uv run --only-group docs zensical build --clean --strict
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

attache-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,119 @@
+name: Release
+
+# Cutting a release is: bump `__version__` in src/attache/__init__.py, merge, tag `vX.Y.Z` on
+# main, push the tag. Everything below happens on the tag. See RELEASING.md.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+# Actions are pinned to commit SHAs: this workflow can publish to PyPI and write releases.
+jobs:
+  verify:
+    name: verify tag matches package version
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      prerelease: ${{ steps.version.outputs.prerelease }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      # First and dependency-free: a tag that disagrees with __version__ should cost seconds,
+      # not a full test matrix.
+      - id: version
+        shell: python
+        run: |
+          import ast, os, re, sys
+          tree = ast.parse(open("src/attache/__init__.py", encoding="utf-8").read())
+          version = next(
+              node.value.value
+              for node in tree.body
+              if isinstance(node, ast.Assign) and node.targets[0].id == "__version__"
+          )
+          tag = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          if tag != version:
+              sys.exit(f"tag v{tag} does not match __version__ {version}")
+          prerelease = bool(re.search(r"(a|b|rc|dev)\d*$", version))
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as out:
+              out.write(f"version={version}\nprerelease={str(prerelease).lower()}\n")
+
+  ci:
+    name: ci
+    needs: verify
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    name: build release artifacts
+    needs: [verify, ci]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - run: uv build
+      - name: Check the metadata PyPI will render
+        run: uvx twine check --strict dist/*
+      # The wheel filename is what gets uploaded, so assert on it rather than trusting that the
+      # build backend read the same version the verify job did.
+      - name: Confirm the artifacts carry the tagged version
+        env:
+          VERSION: ${{ needs.verify.outputs.version }}
+        run: |
+          set -euo pipefail
+          test -f "dist/attache-${VERSION}-py3-none-any.whl" || { ls -1 dist; exit 1; }
+          test -f "dist/attache-${VERSION}.tar.gz" || { ls -1 dist; exit 1; }
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: dist
+          path: dist/
+          retention-days: 30
+
+  publish:
+    name: publish to PyPI
+    needs: [verify, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    # Trusted Publishing: PyPI accepts uploads from this repository, this workflow file and this
+    # environment, with no API token stored anywhere. The environment is also where a manual
+    # approval gate goes, should you ever want one before an upload.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/attache
+    permissions:
+      id-token: write  # mints the short-lived OIDC token PyPI exchanges for an upload token
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  github-release:
+    name: create the GitHub release
+    needs: [verify, publish]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0  # --generate-notes diffs against the previous tag
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          name: dist
+          path: dist/
+      # Last, so a release never claims success for an upload that failed.
+      - name: gh release create
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PRERELEASE: ${{ needs.verify.outputs.prerelease }}
+        run: |
+          set -euo pipefail
+          flags=(--generate-notes --verify-tag --title "${GITHUB_REF_NAME}")
+          if [ "${PRERELEASE}" = "true" ]; then
+            flags+=(--prerelease)
+          fi
+          gh release create "${GITHUB_REF_NAME}" "${flags[@]}" dist/*

attache-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.claude/
+.idea/
+.vscode/
+site/

attache-0.0.1/CLAUDE.md

@@ -0,0 +1,75 @@
+# Attaché: notes for agents and contributors
+
+Attaché is a personal assistant packaged as a Python tool (`uvx attache`). The core is small on
+purpose. Channels, email, file formats and integrations are **skills**, not core code. The
+design is in `docs/proposal.html`; read §3 (architecture) and §10 (code budget) first.
+
+## Commands
+
+```
+uv sync                      # install dev environment
+uv run pytest                # all tests, including the size budget
+uv run ruff check . && uv run ruff format --check .
+uv run attache --help
+uv run --group docs zensical serve   # docs site (zensical.toml, docs/); build with --strict
+```
+
+The web UI, the bundled page kit and the docs site all use the OpenAfterHours design tokens
+(`src/attache/static/oah-tokens.css`, vendored from rwa_calculator; a test guards drift). Fonts
+are self-hosted in `src/attache/static/fonts/` (SIL OFL), so nothing loads from the internet.
+
+## Layout
+
+```
+src/attache/
+  types.py      shared dataclasses and protocols; every module talks through these
+  app.py        builds Services and runs everything
+  config.py     attache.toml -> Config; init_home()
+  store.py      SQLite: messages, docs, tasks, sessions
+  skills.py     skill discovery, prompt index, git commit/log/undo of <home>
+  scheduler.py  fires due tasks
+  agent.py      shared tool loop for API backends
+  backends/     anthropic, openai (chat + responses), claude_cli
+  tools.py      the tools a turn may use, filtered by role
+  router.py     inbound message -> access, trigger, role -> turn -> reply
+  channels.py   channel manager, terminal channel
+  web.py        Starlette app: chat page, artifacts, data bridge, SSE, MCP endpoint for
+                Claude Code (POST /mcp/{token})
+  cli.py        argparse entry point
+  static/       ui.html, bridge.js
+  bundled/      attache.toml template, memory templates, bundled skills (copied by init)
+```
+
+## Rules
+
+1. **Size is a test.** `tests/test_budget.py` fails above 1,600 lines of code in
+   `src/attache` (target about 1,500). Blank lines, comments and docstrings don't count, so
+   never make code denser to fit: write the readable version. Bundled skills are excluded;
+   each bundled skill's scripts have a 300-line cap. If a feature doesn't fit, it belongs in a
+   skill.
+2. **No new runtime dependencies** without discussion. Skill scripts declare their own with
+   PEP 723 headers and run through `uv run`.
+3. **Tests run offline.** No network, no API keys, no real `claude` binary. Inject fakes
+   (every backend takes a `client`/`runner` argument for this).
+4. **Cross-platform.** Windows, macOS and Linux. Use pathlib, `encoding="utf-8"` on every text
+   read and write, argument lists for subprocesses (no shell unless the `run` tool), and no
+   POSIX-only APIs.
+5. **Style.** ruff with the repo config, `from __future__ import annotations`, type hints on
+   public functions, short docstrings on public functions only, comments only for a
+   non-obvious why. Plain functions and dataclasses over class hierarchies.
+6. **Security model.**
+   - Roles are owner, member and guest (router.py). Only the owner's own chats get file, shell
+     and memory tools; an owner turn inside a group gets member tools, because group context is
+     untrusted. Non-owner turns never use the `claude-cli` backend (Anthropic's terms).
+   - Members act only on docs shared with their chat. Other people's messages reach the model
+     fenced and labelled as data; display names are never trusted.
+   - Text from tools, emails and web pages is untrusted data, never instructions.
+   - Artifact pages are hostile HTML: served with a CSP sandbox (opaque origin, no outbound
+     requests) and only inside the Attaché window. The owner's UI token is random per run and
+     only reaches the browser through the link Attaché prints.
+   - The web server binds loopback only in phase 1. Tokens are compared with
+     `hmac.compare_digest`; page tokens derive from the per-run UI token, so they rotate too.
+   - `claude -p` runs in `<home>-claude`, outside the home, so files in `<home>` never load as
+     Claude Code project config.
+7. **Contracts live in `types.py`** and the module docstrings. Change a public signature only
+   together with every caller and its tests.

attache-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Attaché stays small so anyone can read the core in an afternoon and change it with confidence.
+
+**Accepted in the core:** bug fixes, security fixes, simplifications, less code.
+
+**Not accepted in the core:** features, integrations, channels, file formats. These should be
+skills. (This rule comes from [nanoclaw](https://github.com/nanocoai/nanoclaw).)
+
+## Adding a skill
+
+A skill is a folder with a `SKILL.md` in the [Agent Skills](https://agentskills.io/specification)
+format:
+
+```
+skills/<name>/
+  SKILL.md          frontmatter: name, description, optional metadata
+  scripts/*.py      optional; PEP 723 header declares dependencies, run with `uv run`
+  templates/        optional; artifact templates
+```
+
+Metadata keys Attaché reads:
+
+- `attache-roles: "member"` makes the skill available in group chats: members see its full
+  text in their prompt and may run its scripts. Without it a skill is owner-only.
+- `attache-channel: "<command>"` marks a channel sidecar (phase 2).
+
+Bundled skills live in `src/attache/bundled/skills/` and are copied into a user's home by
+`attache init`. Each bundled skill's scripts are capped at 300 lines of code by
+`tests/test_budget.py`.
+
+## The size budget
+
+`tests/test_budget.py` fails when the core passes 1,600 lines of code. Blank lines, comments
+and docstrings don't count, so write the clearest version of the code, not the shortest.
+
+## Before you open a pull request
+
+```
+uv run ruff check . && uv run ruff format --check .
+uv run pytest
+```

attache-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenAfterHours contributors
+
+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.

attache-0.0.1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: attache
+Version: 0.0.1
+Summary: A personal assistant you install with one command. Small core; channels, email and file formats are skills.
+Project-URL: Homepage, https://github.com/OpenAfterHours/attache
+Project-URL: Repository, https://github.com/OpenAfterHours/attache
+Project-URL: Issues, https://github.com/OpenAfterHours/attache/issues
+Author: OpenAfterHours contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,assistant,claude,local-first,openai,skills
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40
+Requires-Dist: cronsim>=2.6
+Requires-Dist: openai>=1.66
+Requires-Dist: pyyaml>=6
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# Attaché
+
+A personal assistant you install with one command. It runs on your own machine, keeps your
+to-dos and reminders, makes interactive pages on demand, and learns how you work through a
+folder of skills it can edit itself. The core is just under 1,600 lines of Python code, the
+cap CI enforces; everything else is a skill.
+
+> **Status:** phase 1 of the [roadmap](docs/proposal.html): the local core, terminal and web
+> chat. Slack and Signal arrive in phase 2, email (Outlook, Gmail, Titan) in phase 3.
+
+**Documentation:** <https://openafterhours.github.io/attache/>.
+
+## Try it
+
+```
+uvx attache              # first run asks your name, creates ~/.attache, then opens a chat
+uv tool install attache  # keep it
+attache chat             # terminal chat, plus the web page
+attache run              # web page, reminders and channels, no terminal chat
+attache doctor           # check your setup
+```
+
+![The web page: chat on the left, the Home page with to-dos and reminders on the right](docs/phase-1-ui.png)
+
+The terminal and the web page are one conversation. Attaché prints a link like
+`http://127.0.0.1:8765/#t=...` when it starts; open that link to use the web page. The token in
+it changes every run, so other programs on your machine can't drive your assistant.
+
+Attaché talks to models through four adapters, chosen in `~/.attache/attache.toml`:
+
+| `api`              | Use it for                                                        |
+|--------------------|-------------------------------------------------------------------|
+| `claude-cli`       | Claude Code (`claude -p`) on your own login. Your own chats only. |
+| `anthropic`        | The Claude API, or any Anthropic-compatible `base_url`            |
+| `openai-chat`      | Ollama, LM Studio, vLLM, llama.cpp, OpenRouter, Groq, Azure       |
+| `openai-responses` | OpenAI reasoning models with tools                                |
+
+```toml
+[routing]
+own_chats   = "claude"      # your Claude login
+group_chats = "claude-api"  # an API key, per Anthropic's terms
+
+[endpoints.claude]
+api   = "claude-cli"
+model = "claude-sonnet-5-5"
+
+[endpoints.claude-api]
+api     = "anthropic"
+model   = "claude-sonnet-5-5"
+key_env = "ANTHROPIC_API_KEY"
+```
+
+## How it is put together
+
+- **Skills** live in `~/.attache/skills/<name>/SKILL.md` ([Agent Skills](https://agentskills.io)
+  format). Only names and descriptions go into the prompt. The assistant edits skills when you
+  change how you work, and `~/.attache` is a git repo, so `attache skills log` and
+  `attache skills undo <name>` show and reverse every change.
+- **Artifacts** are HTML pages the assistant writes into `~/.attache/artifacts/`. The local web
+  server adds a small `attache` bridge so a page can read and write real data with live updates.
+  Pages run sandboxed: they can't reach the internet or anything outside the data they declare.
+- **Roles.** You are the owner. Group members (from phase 2) only reach what is shared with
+  their chat, and never files, shell or email. Your own turns inside a group get member tools
+  too, because the group's messages are untrusted.
+- **Claude Code** runs as a backend with `claude -p` on your own login, for your own chats only.
+  Attaché's tools reach it through an MCP endpoint on the local web server. It runs in a
+  working folder next to your home (`~/.attache-claude`), so nothing written into `~/.attache`
+  can load as Claude Code project settings.
+
+The full design, with the research behind it, is in [docs/proposal.html](docs/proposal.html).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md): bug fixes and simplifications go in the core, features
+go in skills.
+
+## License
+
+MIT

attache-0.0.1/README.md

@@ -0,0 +1,79 @@
+# Attaché
+
+A personal assistant you install with one command. It runs on your own machine, keeps your
+to-dos and reminders, makes interactive pages on demand, and learns how you work through a
+folder of skills it can edit itself. The core is just under 1,600 lines of Python code, the
+cap CI enforces; everything else is a skill.
+
+> **Status:** phase 1 of the [roadmap](docs/proposal.html): the local core, terminal and web
+> chat. Slack and Signal arrive in phase 2, email (Outlook, Gmail, Titan) in phase 3.
+
+**Documentation:** <https://openafterhours.github.io/attache/>.
+
+## Try it
+
+```
+uvx attache              # first run asks your name, creates ~/.attache, then opens a chat
+uv tool install attache  # keep it
+attache chat             # terminal chat, plus the web page
+attache run              # web page, reminders and channels, no terminal chat
+attache doctor           # check your setup
+```
+
+![The web page: chat on the left, the Home page with to-dos and reminders on the right](docs/phase-1-ui.png)
+
+The terminal and the web page are one conversation. Attaché prints a link like
+`http://127.0.0.1:8765/#t=...` when it starts; open that link to use the web page. The token in
+it changes every run, so other programs on your machine can't drive your assistant.
+
+Attaché talks to models through four adapters, chosen in `~/.attache/attache.toml`:
+
+| `api`              | Use it for                                                        |
+|--------------------|-------------------------------------------------------------------|
+| `claude-cli`       | Claude Code (`claude -p`) on your own login. Your own chats only. |
+| `anthropic`        | The Claude API, or any Anthropic-compatible `base_url`            |
+| `openai-chat`      | Ollama, LM Studio, vLLM, llama.cpp, OpenRouter, Groq, Azure       |
+| `openai-responses` | OpenAI reasoning models with tools                                |
+
+```toml
+[routing]
+own_chats   = "claude"      # your Claude login
+group_chats = "claude-api"  # an API key, per Anthropic's terms
+
+[endpoints.claude]
+api   = "claude-cli"
+model = "claude-sonnet-5-5"
+
+[endpoints.claude-api]
+api     = "anthropic"
+model   = "claude-sonnet-5-5"
+key_env = "ANTHROPIC_API_KEY"
+```
+
+## How it is put together
+
+- **Skills** live in `~/.attache/skills/<name>/SKILL.md` ([Agent Skills](https://agentskills.io)
+  format). Only names and descriptions go into the prompt. The assistant edits skills when you
+  change how you work, and `~/.attache` is a git repo, so `attache skills log` and
+  `attache skills undo <name>` show and reverse every change.
+- **Artifacts** are HTML pages the assistant writes into `~/.attache/artifacts/`. The local web
+  server adds a small `attache` bridge so a page can read and write real data with live updates.
+  Pages run sandboxed: they can't reach the internet or anything outside the data they declare.
+- **Roles.** You are the owner. Group members (from phase 2) only reach what is shared with
+  their chat, and never files, shell or email. Your own turns inside a group get member tools
+  too, because the group's messages are untrusted.
+- **Claude Code** runs as a backend with `claude -p` on your own login, for your own chats only.
+  Attaché's tools reach it through an MCP endpoint on the local web server. It runs in a
+  working folder next to your home (`~/.attache-claude`), so nothing written into `~/.attache`
+  can load as Claude Code project settings.
+
+The full design, with the research behind it, is in [docs/proposal.html](docs/proposal.html).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md): bug fixes and simplifications go in the core, features
+go in skills.
+
+## License
+
+MIT

attache-0.0.1/RELEASING.md

@@ -0,0 +1,68 @@
+# Releasing attache
+
+A release is a pushed tag. The tag check, the full CI matrix, the build, the PyPI upload and the
+GitHub release all happen in `.github/workflows/release.yml`.
+
+## One-time setup: PyPI Trusted Publishing
+
+attache uploads to PyPI over OIDC. There is no API token in this repository and there should
+never be one. PyPI needs to be told, once, which workflow it accepts uploads from.
+
+`attache` has not been published yet, so this is a **pending publisher**. It becomes an ordinary
+publisher the moment the first release lands, and that release also claims the name.
+
+1. Sign in at <https://pypi.org> and open **Account settings → Publishing**.
+2. Under *Add a new pending publisher*, choose **GitHub** and fill in exactly:
+
+   | Field | Value |
+   |---|---|
+   | PyPI project name | `attache` |
+   | Owner | `OpenAfterHours` |
+   | Repository name | `attache` |
+   | Workflow name | `release.yml` |
+   | Environment name | `pypi` |
+
+3. Save. All five fields must match or the upload is rejected. The environment name in
+   particular is easy to leave blank, and it is part of the claim.
+
+### The `pypi` environment
+
+The `publish` job runs in a GitHub environment named `pypi`; GitHub creates it on the first
+release. It pins the Trusted Publishing claim, and it is where an approval gate goes:
+
+- **Settings → Environments → pypi → Required reviewers** makes a person approve each upload.
+  Leave it unprotected and a pushed tag publishes on its own, which is the intended default.
+- A tag ruleset (**Settings → Rules → Rulesets**, target `v*`) limits who can create release
+  tags. Without one, anyone with write access can publish by pushing a tag.
+
+## Cutting a release
+
+Versions follow PEP 440. The single source of truth is `__version__` in
+`src/attache/__init__.py`; `pyproject.toml` reads it.
+
+1. Bump `__version__` in a pull request and merge it once CI is green.
+2. Tag the merge commit on `main` and push the tag:
+
+   ```bash
+   git checkout main
+   git pull
+   git tag v0.0.1
+   git push origin v0.0.1
+   ```
+
+3. Watch **Actions → Release**. In order, it:
+   - checks the tag matches `__version__`;
+   - runs the whole CI workflow (lint, tests on Ubuntu, Windows and macOS, the wheel smoke test);
+   - builds the sdist and wheel and checks their metadata with `twine check --strict`;
+   - uploads them to PyPI;
+   - creates the GitHub release with generated notes and both files attached.
+
+A tag that doesn't match `__version__` fails in the first job, before anything is built. Versions
+ending in `a`, `b`, `rc` or `dev` (for example `0.1.0rc1`) are marked as pre-releases on GitHub.
+
+## If a release fails
+
+- **Before the publish job:** fix the problem on `main`, delete the tag
+  (`git push --delete origin v0.0.1` and `git tag -d v0.0.1`), and tag again.
+- **After the upload:** PyPI never accepts the same version twice. Bump to the next version and
+  release that.