axism 0.1.1__tar.gz

axism-0.1.1/.github/copilot-instructions.md

@@ -0,0 +1 @@
+See [AGENTS.md](../AGENTS.md) at the repository root for contributor and coding-agent instructions.

axism-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Python
+        run: uv python install 3.12
+
+      - name: Sync
+        run: uv sync --extra dev
+
+      - name: Ruff
+        run: uv run ruff check src tests
+
+      - name: Pytest
+        run: uv run pytest -q
+
+      - name: Anonymity
+        run: uv run python scripts/check_anonymity.py

axism-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write
+      id-token: write  # Trusted Publisher (OIDC) → PyPI
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Python
+        run: uv python install 3.12
+
+      - name: Build
+        run: |
+          uv sync --extra dev
+          uv build
+          ls -la dist
+
+      - name: Upload GitHub release assets
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Creates the PyPI project on first successful upload when a
+      # pending Trusted Publisher is registered for this workflow.
+      # See: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

axism-0.1.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.swp
+.DS_Store
+uv.lock

axism-0.1.1/AGENTS.md

@@ -0,0 +1,87 @@
+# Agent instructions for aXism
+
+**aXism** (*Agent Interactive Session Manager*) is a TUI + CLI session manager for Claude Code, Cursor, and Hermes. Keep the product name and binary **`axism`** agent-agnostic.
+
+## Stack
+
+- Python 3.12+, Textual, uv, hatchling
+- Binary: `axism`
+- Package: `axism` under `src/axism/`
+- Display name: **aXism**
+
+## Hard rules
+
+1. **Anonymity** — no hostnames, forge URLs, personal home paths, or secrets in tracked files. Fixtures use synthetic `/home/alice/...` or `/Users/alice/...` only. Run `python3 scripts/check_anonymity.py`.
+2. **Protected paths** — never delete credentials, agent config, skills, plugins, daemon keys, project `memory/`, or a backend's whole database with a normal session delete. `fragments.PROTECTED_NAMES` is shared by every provider.
+3. **Subprocess** — argv lists only; never `shell=True`.
+4. **Go through the provider** — TUI and CLI call `SessionProvider` methods only. Never import `discover` / `live` / `rename` / `move` / `delete` / `fragments` directly from `cli.py` or `tui/app.py`; those are Claude Code's implementation, wrapped by `ClaudeCodeProvider`.
+5. **Unsupported means explicit** — declare it in `Capabilities`, then raise `UnsupportedOperation` (or return a failed `MoveResult` / `(False, message)`). Never silently no-op.
+6. **Stop** — `s`/`S` targets whatever `provider.can_stop(live)` allows: Claude Code background jobs via ``claude stop``, otherwise the agent process. Never map Stop onto a global switch such as `hermes pause`.
+7. **Pane-aware keys** — Space / a / d / o / s / m follow the projects vs sessions matrix; **c/C clears all marks** (projects + sessions). **d/D** deletes projects when the projects pane is focused, sessions otherwise. **m/M moves** project(s) or session(s) to another path (pick existing or type cwd) within the same agent tool. **`,`** opens Settings (include backends + config dirs). Enabled backends are federated into one inventory; marks/live use `provider:id` keys.
+8. User-facing branding says **aXism**. Name a specific agent only where the code shells out to it.
+9. **Docs are current-state only** — README and similar docs describe how the project works *now*, not how it evolved. Prefer editing content in place over phrases like “was removed,” “previously,” “used to,” “as of [date],” or “no longer.” Do not put agent/process meta-commentary into project files. **Exception:** keep `CHANGELOG.md` up to date on every version bump (see Versioning).
+10. **Changelog** — when bumping the version, move `[Unreleased]` notes into a new `## [X.Y.Z] — YYYY-MM-DD` section in `CHANGELOG.md` and leave a fresh empty `[Unreleased]` stub.
+
+## Layout
+
+```text
+src/axism/
+  cli.py, tui/, agents.py, delete.py, discover.py, fragments.py, live.py, move.py,
+  paths.py, rename.py, settings.py     # Claude Code implementation + shared DTOs
+  providers/
+    base.py           # SessionProvider protocol, Capabilities, ProviderBase
+    common.py         # shared helpers for filesystem-backed backends
+    __init__.py       # registry: PROVIDER_LABELS + get_provider
+    claude_code.py    # wraps the top-level modules above
+    cursor.py + cursor_store/     # ~/.cursor agent transcripts + CLI SQLite chats
+    hermes.py + hermes_store/     # ~/.hermes state.db, mutations via the hermes CLI
+tests/                # synthetic alice fixtures
+scripts/install.sh
+scripts/check_anonymity.py
+```
+
+## Provider scope
+
+Each backend manages **default chat sessions only**. Work beyond that belongs on its own branch so the shared protocol stays stable:
+
+| Branch | Scope |
+|--------|-------|
+| `feat/hermes-extras` | Hermes profiles (`profiles/<name>/state.db`), kanban boards (`kanban.db`), `hermes project` workspaces (`projects.db`), messaging/cron sources |
+| `feat/cursor-extras` | Cursor desktop Composer history in the Electron profile (`state.vscdb`) |
+
+If one of those needs a protocol change, extend `SessionProvider` in a way every backend can satisfy — never with a single-backend assumption in `base.py`.
+
+## Adding a provider
+
+1. Create `providers/<name>.py` subclassing `ProviderBase`, plus `providers/<name>_store/` for its layout. Do not import another backend's store package.
+2. Map into the shared DTOs (`ProjectInfo`, `SessionMeta`, `LiveSession`, `Fragment`); use `SessionMeta.entrypoint` for a badge rather than new required fields.
+3. Register the id and label in `providers/__init__.py`, and set `config_hint` for the Settings placeholder.
+4. Prefer the agent's own CLI for mutations when one exists; fall back to filesystem operations only where it does not.
+5. Add tests with synthetic fixtures under `tests/`; never touch a real agent home in a test.
+
+## Dev commands
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check src tests
+python3 scripts/check_anonymity.py
+uv run axism --help
+uv tool install --force .
+```
+
+## Versioning & release
+
+Bump **all** of:
+
+| File | Field / action |
+|------|----------------|
+| `pyproject.toml` | `project.version` |
+| `src/axism/__init__.py` | `__version__` |
+| `CHANGELOG.md` | move `[Unreleased]` → `## [X.Y.Z] — YYYY-MM-DD`; leave empty `[Unreleased]` |
+
+Tag `v*` (e.g. `v0.1.0`) to trigger `.github/workflows/release.yml` (GitHub Release assets + PyPI). Keep docs forge-agnostic (no hardcoded private hosts).
+
+## Commits
+
+Prefer generic messages (“add pane-aware select”, not machine- or customer-specific notes).

axism-0.1.1/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to aXism are documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] — 2026-09-23
+
+### Added
+
+- Cursor provider: IDE agent transcripts (`~/.cursor/projects/<slug>/agent-transcripts/`) and CLI chats (`~/.cursor/chats/<md5-cwd>/<id>/`, both the SQLite and JSON-sidecar shapes), with open, stop, rename, move, and delete
+- Hermes provider: interactive sessions from `~/.hermes/state.db`, opened with `hermes --resume` and mutated through `hermes sessions`
+- `--provider` flag and `axism providers` command
+- Provider `Capabilities`, so keys a backend cannot perform report instead of failing
+- Federated inventory: enable multiple backends in Settings; TUI and `axism list` show them together with an **Agent** column when more than one is active
+- `providers/federation.py` helpers and composite `provider:id` keys for marks/live maps
+- Cross-agent session copy (beta): TUI move to another agent, or `axism export <id> --to-provider … --to /cwd` (text turns; source kept)
+- Hermes inventory includes imported (`claude-code` / `codex`) and `oneshot` sessions; exports stamp the destination cwd
+- Publish tagged releases to PyPI via GitHub Actions Trusted Publisher (OIDC)
+- Project homepage / repository / issues URLs in package metadata
+
+### Changed
+
+- `SessionProvider` covers discovery, liveness, open/stop, fragments, rename, move, and delete; the TUI and CLI no longer reach into Claude Code's modules directly
+- `--config-dir` overrides the active provider's root instead of always setting `$CLAUDE_CONFIG_DIR`
+- Credentials, agent config files, and backend databases are protected for every provider
+- Settings Space = include in inventory; Enter = CLI default (`active_provider`)
+- Move/delete refuse mixed-agent selections; destinations stay within the same agent tool
+- Sessions filter/sort chrome sits under the sessions table; Tab cycles detail → sessions → projects
+- Header shows full brand + version without mid-name ellipsis
+
+### Fixed
+
+- CI pytest collection (`pythonpath` includes project root so `tests.*` imports resolve)
+- Cross-agent transfer into Claude Code now writes `customTitle` so the transferred session keeps its title
+- Hermes delete stops a live session's process before deleting it, matching Claude Code and Cursor
+- Cursor delete now blocks on a genuinely running `cursor-agent` process instead of never blocking
+- Cursor session move no longer reports failure when a session is already at the destination
+
+## [0.1.0] — 2026-09-19
+
+Initial public release.
+
+### Added
+
+- Textual TUI and CLI session manager (`axism`) for Claude Code configs
+- Cross-project inventory: list, open, stop, rename, move, delete
+- Pane-aware projects / sessions / detail layout with essential footer bindings
+- Settings for active provider and config directory
+- Session filter and sort in the sessions pane
+- Safe delete with confirm; project delete uses a stronger danger confirm
+- Project move with memory merge and optional agent handoff on dual `MEMORY.md`
+- GitHub Actions CI (pytest, ruff, anonymity check) and tagged GitHub Releases
+- Install via `scripts/install.sh` / `uv tool install`

axism-0.1.1/LICENSE

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

axism-0.1.1/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.5
+Name: axism
+Version: 0.1.1
+Summary: aXism — Agent Interactive Session Manager (TUI + CLI)
+Project-URL: Homepage, https://github.com/aXistem-dev/axism
+Project-URL: Repository, https://github.com/aXistem-dev/axism
+Project-URL: Issues, https://github.com/aXistem-dev/axism/issues
+Project-URL: Changelog, https://github.com/aXistem-dev/axism/blob/main/CHANGELOG.md
+Author: aXism contributors
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,axism,claude-code,sessions,tui
+Requires-Python: >=3.12
+Requires-Dist: textual>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aXism
+
+**Agent Interactive Session Manager** — list, inspect, open, stop, rename, move, and purge coding-agent chat sessions and their on-disk fragments across every project on your machine.
+
+**Current version: `0.1.0`** (`pyproject.toml` / `axism --version`)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](pyproject.toml)
+[![CI](https://img.shields.io/badge/CI-pytest%20%2B%20ruff-brightgreen.svg)](.github/workflows/ci.yml)
+
+<p align="center">
+  <a href="https://buymeacoffee.com/confituurke">
+    <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50" width="217" />
+  </a>
+</p>
+
+Works on **Linux** and **macOS**, across three agent backends:
+
+| Provider | Id | Session store | Config override |
+|----------|----|---------------|-----------------|
+| [Claude Code](https://code.claude.com/) (default) | `claude_code` | `projects/<slug>/<uuid>.jsonl` | `$CLAUDE_CONFIG_DIR` or `~/.claude` |
+| Cursor | `cursor` | `projects/<slug>/agent-transcripts/<id>/` and `chats/<md5-cwd>/<id>/` | `$CURSOR_DATA_DIR` or `~/.cursor` |
+| Hermes | `hermes` | `state.db` (`sessions` + `messages`) | `$HERMES_HOME` or `~/.hermes` |
+
+Enable any combination in Settings (`,`) in the TUI — Space includes a backend in the inventory; Enter sets the CLI default. Use `--provider` on the CLI to scope one command to a single backend.
+
+## Features
+
+- Cross-project session inventory with sizes, tags, and live/background state
+- Pane-aware Textual TUI: **projects (25%) · sessions (50%) · detail**
+  - Detail shows **project** summary when the projects pane is focused; **session** detail otherwise
+  - Footer only lists essentials (plus Settings / Help); `?` has the full key legend
+  - Theme-aware markup (`t` picker / `T` cycle)
+- Mark, open, stop, rename, **move**, and delete — all respect focus and multi-select
+- **Delete** is pane-aware: `d` on projects deletes projects; `d` on sessions deletes sessions (project delete confirm uses a stronger danger style)
+- Move projects or sessions to another project (pick existing or type a path)
+- Project moves merge `memory/` into the destination (colliding names get a `-from-<slug>` suffix; dual `MEMORY.md` can hand off to a local agent CLI)
+- Settings (`,`) to include backends in the inventory and set config directories (`~/.config/axism/settings.json`)
+- When more than one agent is enabled, the projects pane shows an **Agent** column
+- Safe delete with confirm (stops live processes when deleting)
+- Header shows brand with version/commit beside it; `v` for runtime details
+- Sessions pane: `/` filter, `.` cycle sort (updated / title / size)
+- Open sessions via the provider CLI (`claude attach` / `claude --resume`, `cursor-agent --resume`, `hermes --resume`)
+- Keys that a backend cannot perform say so instead of failing halfway
+- Headless CLI for scripting
+
+## Install
+
+```bash
+# once published to PyPI
+pipx install axism
+# or
+uv tool install axism
+```
+
+From GitHub release assets:
+
+```bash
+uv tool install https://github.com/aXistem-dev/axism/releases/download/v0.1.0/axism-0.1.0-py3-none-any.whl
+```
+
+From a clone (development):
+
+```bash
+./scripts/install.sh
+# or: uv tool install --force .
+```
+
+Ensure `~/.local/bin` is on your `PATH`. Then:
+
+```bash
+axism --version   # e.g. axism 0.1.0
+axism --help
+```
+
+## Quick start
+
+```bash
+axism          # TUI
+axism tui
+axism list
+axism list --project /home/alice/src/demo
+axism list --json
+```
+
+## Keyboard (TUI)
+
+Actions are **pane-aware**. Most letter keys accept both cases (`a` / `A`, `q` / `Q`, …). The footer hides keys that cannot run right now (e.g. Open/Rename/Stop on the projects pane, Stop when nothing is stoppable). Press **`?`** / **`h`** for the full legend.
+
+| Key | Projects pane | Sessions / detail |
+|-----|---------------|-------------------|
+| `Tab` | Switch pane (detail → sessions → projects) | Same |
+| `Shift+Tab` / `←` / `→` | Switch pane (`←`/`→` spatial) | Same |
+| `↑` / `↓` | Move in list | Move in list |
+| `Space` | Mark project | Mark session (no-op on detail) |
+| `a` / `A` | Select all projects | Select all sessions in project |
+| `c` / `C` | Clear **all** marks (projects + sessions) | Clear **all** marks |
+| `o` / `O` | — | **Open** — live background → `claude attach`; else `claude --resume` |
+| `s` / `S` | — | **Stop** background session(s) (same as `/stop` while attached) |
+| `n` / `N` | — | **Rename** focused session |
+| `m` / `M` | **Move** marked/focused project(s) | **Move** marked/focused session(s) |
+| `/` | — | Focus session filter |
+| `.` | — | Cycle session sort |
+| `d` / `D` | Delete marked/focused project(s) | Delete marked/focused session(s) |
+| `r` / `R` | Refresh | Refresh |
+| `t` | Theme picker | Theme picker |
+| `T` | Cycle theme | Cycle theme |
+| `,` | Settings (include agents + config dirs) | Settings |
+| `v` / `V` | Version details | Version details |
+| `?` / `h` | Help | Help |
+| `q` / `Q` | Quit | Quit |
+
+**Move** opens a dialog: pick another project from the list (↑/↓), or **Tab** to the path field and type an absolute workspace path (**Shift+Tab** returns to the list). One project → a new path renames the Claude project directory and creates the workspace folder if needed (source tree files stay put); otherwise sessions and `memory/` are merged into the destination. Live/background sessions must be stopped first. If both sides have `MEMORY.md`, aXism offers a handoff to a detected agent CLI (`claude`, `cursor`, `opencode`, `aider`, `codex`, …) or saves a task brief only.
+
+Confirm dialogs use `y` / `n` / `Esc`.
+
+## CLI
+
+```bash
+axism --version
+axism list
+axism list --project /home/alice/src/demo
+axism list --json
+axism show <session-uuid>
+axism resume <session-uuid>
+axism resume <session-uuid> --print-only
+axism stop <session-uuid> --yes
+axism rename <session-uuid> "New title"
+axism move <session-uuid> [<uuid>…] --to /home/alice/src/other
+axism move --project /home/alice/src/demo --to /home/alice/src/other
+axism move --project -home-alice-src-demo --to /home/alice/src/other --dry-run
+axism move --project /home/alice/src/demo --to /home/alice/src/other --memory-agent auto
+axism move --project /home/alice/src/demo --to /home/alice/src/other --memory-agent claude --memory-agent-force
+axism move --project /home/alice/src/demo --to /home/alice/src/other --no-merge-memory
+axism export <session-uuid> --to-provider hermes --to /home/alice/src/demo
+axism export <session-uuid> --to-provider cursor --to /home/alice/src/other --dry-run
+axism delete <session-uuid> --dry-run
+axism delete <uuid-a> <uuid-b> --yes
+axism delete-project /home/alice/src/demo --dry-run
+axism delete-project -home-alice-src-demo --yes
+axism delete-project -home-alice-src-demo --yes --keep-memory
+axism purge-project /home/alice/src/demo --dry-run   # wraps: claude project purge
+```
+
+Global flags: `--provider {claude_code,cursor,hermes}`, `--config-dir`, `--no-cli` (skip agent-CLI live enrichment), `--version`.
+
+```bash
+axism providers                      # backends, enabled state, and resolved roots
+axism --provider cursor list
+axism --provider hermes show <session-id>
+```
+
+TUI **Settings** (`,`) stores which backends are included (`enabled`), the CLI default (`active_provider`), and optional per-backend config dirs in `~/.config/axism/settings.json` (or `$AXISM_CONFIG_DIR`). The TUI and `axism list` merge every enabled backend; `--provider` scopes one CLI command to a single backend; `--config-dir` overrides that backend's root. Same-agent move/delete refuse mixed marks. Session **move** to another agent copies text turns (source kept); use `axism export` for the same from the CLI.
+
+## Backend differences
+
+Every backend implements the same provider interface, and each one refuses what its agent genuinely cannot do:
+
+| Capability | Claude Code | Cursor | Hermes |
+|------------|-------------|--------|--------|
+| Open / resume | `claude attach` or `claude --resume` | `cursor-agent --resume` | `hermes --resume` |
+| Stop | `claude stop` on background jobs | ends the `cursor-agent` process | ends the `hermes` process |
+| Rename | `custom-title` transcript record | `store.db` name / title sidecar | `hermes sessions rename` |
+| Move sessions / projects | yes, with `memory/` merge | yes (relocates chat dirs) | not supported |
+| Delete session | fragment plan across the tree | removes the chat dir in each store | `hermes sessions delete` |
+| Project purge | `claude project purge` | not supported | not supported |
+
+Hermes reads `state.db` read-only and only lists interactive sources (`cli`, `tui`, `desktop`, `webui`) — cron and kanban worker sessions stay hidden.
+
+A Cursor chat started from the CLI exists in both stores under one id; aXism shows it once and treats both directories as its fragments. CLI chats come in two shapes — a SQLite `store.db` (its `name` is the title) and newer `meta.json` + `prompt_history.json` sidecars (title comes from the first real prompt) — and both are listed.
+
+### Not managed
+
+These stores are intentionally left alone:
+
+- Hermes named profiles (`~/.hermes/profiles/<name>/`, each with its own `state.db`), kanban boards (`kanban.db`), and `hermes project` workspaces (`projects.db`)
+- Hermes gateway/messaging sessions (Telegram, Discord, Slack, …) and cron runs
+- Cursor's desktop Composer history in the Electron profile (`~/.config/Cursor` / `~/Library/Application Support/Cursor`)
+
+## How it works
+
+aXism scans every **enabled** provider config root, maps each session id to its transcripts, jobs, subagents, caches, and live records (namespaced per backend), then lets you open, stop, rename, move, or delete those fragments without touching protected global state. The TUI and CLI only ever call the provider interface in [`src/axism/providers/base.py`](src/axism/providers/base.py); each backend owns its own layout under `providers/<name>_store/`.
+
+Claude Code's tree:
+
+```text
+configRoot
+├── projects/<slug>/<uuid>.jsonl     transcripts
+├── projects/<slug>/<uuid>/          subagents / tool-results
+├── projects/<slug>/memory/          project memory (protected on session delete)
+├── file-history/<uuid>/
+├── jobs/<short8>/
+├── sessions/<pid>.json              live registry
+└── history.jsonl                    prompt index (rewritten on delete / move)
+```
+
+Project slugs are Claude Code’s encoding of an absolute cwd (non-alphanumeric → `-`).
+
+**Move** relocates session files between `projects/<slug>/` dirs (or renames a whole project dir), rewrites **all** transcript `cwd` fields to the destination, updates `history.jsonl` / job `cwd` when present, creates the destination workspace folder if it does not exist (it does **not** move your source tree files), and leaves UUID-keyed fragment trees (`file-history`, …) in place. Project merges also merge `memory/` (unique files move; content collisions become `-from-<slug>` names; dual `MEMORY.md` parks the source index for an optional agent handoff).
+
+## What is protected
+
+Never deleted with a session: credentials (`auth.json`, `.credentials.json`, `.env`), agent config (`settings.json`, `config.yaml`, `cli-config.json`), skills, plugins, daemon keys, project `memory/`, the Hermes `state.db`, and unrelated global caches.
+
+**Project delete** removes `projects/<slug>/` (memory unless `--keep-memory`) plus linked session fragments outside that directory.
+
+## Build from source
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check src tests
+python3 scripts/check_anonymity.py
+uv build                          # dist/axism-0.1.0-*.whl and *.tar.gz
+./scripts/install.sh              # reinstall tool + print axism --version
+```
+
+## Versioning
+
+Bump **all** when releasing:
+
+| File | Field |
+|------|--------|
+| `pyproject.toml` | `project.version` |
+| `src/axism/__init__.py` | `__version__` |
+| `CHANGELOG.md` | new `[X.Y.Z]` section from `[Unreleased]` |
+
+```bash
+axism --version          # installed binary
+# → axism 0.1.0
+```
+
+Tag `v*` (e.g. `v0.1.0`) to trigger the release workflow.
+
+## Releases & CI
+
+- **CI** (`.github/workflows/ci.yml`): pytest, ruff, anonymity check — works on GitHub Actions and Forgejo/Gitea/Codeberg Actions.
+- **Release** (`.github/workflows/release.yml`): on tag `v*`, builds wheel/sdist, uploads GitHub release assets, and publishes to PyPI via Trusted Publisher (OIDC).
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+## Contributing
+
+See [AGENTS.md](AGENTS.md) for coding-agent and human contributor rules (anonymity, pane-aware keys, safe delete / move).
+
+## Support
+
+[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png)](https://buymeacoffee.com/confituurke)
+
+## License
+
+[MIT](LICENSE) © aXism contributors