agent-box-tool 1.0.0__tar.gz

agent_box_tool-1.0.0/AGENTS.md

@@ -0,0 +1,174 @@
+<!-- BEGIN AGENT-BOX workflow sha256=92395bc8ed359eb4df1606ec6a97757e1ee9c2ef82532f1c2614f912651942a4 -->
+Read the tracked task before work; .agent-box.json binds this repository to its tracker project.
+Use agent-box tracker for task state, progress and dependencies; read related history when context is missing.
+Use ab-interview, ab-plan, ab-work, ab-sync, ab-review, ab-pr, and ab-land as needed. ab-setup maintains this binding and ab-adopt brings an existing project in line with the workflow; ab-normalize processes unmarked tasks in a bound project.
+The coordinator owns branches, commits, lifecycle, dependencies, and GitHub actions. Delegate implementation sequentially and research to scouts, which may run in parallel, when their model lists are configured; with an empty list the coordinator does that work itself.
+A worker changes project files and answers; scouts and a fresh reviewer only read. Plan sync reads the repository and updates tracker descriptions and comments through agent-box tracker; it never changes project files, Git or lifecycle. The coordinator verifies answers and findings and commits what it accepts.
+Tracker comments are a human journal. Branch, base branch, and pull request come from Git and GitHub; lifecycle comes from the tracker's own fields, never from comment text.
+Use the user's language for all coordinator messages to them: progress updates, questions, option explanations and final answers. Literal project labels may stay quoted in the project language. Write tracker text, GitHub text, commit messages, code comments and documentation in the `language` that `agent-box tracker status` and `workflow inspect` report; when it is null, use the task's language in the tracker and English for implementation. Agent-to-agent handoffs and reports stay English; agent-box CLI output, errors and help stay English.
+Complete subtasks only after validation and integration into the parent branch; complete parents only after merge into the base branch.
+<!-- END AGENT-BOX workflow -->
+
+# agent-box — notes for agents working on this repository
+
+## What this is
+
+A launcher. `agent-box` runs Claude Code and Codex CLI inside rootless Podman
+workspace boxes. Python standard library at runtime, packaged as `agent-box-tool` with no
+runtime dependencies. Install editable for development; uv/pipx own the public
+`agent-box` command and package updates.
+
+```text
+pyproject.toml         package metadata and agent-box -> agent_box.cli:main
+agent_box/cli.py       argument parsing and command dispatch
+agent_box/config_menu.py stdlib curses configuration menu
+agent_box/tracker/     portable task contract and product adapters
+agent_box/workflow.py  deterministic workflow boundaries; skills orchestrate
+agent_box/runtime.py   container lifecycle, mounts, launches, doctor
+agent_box/config.py    the whole config schema; flat dataclasses, no framework
+agent_box/paths.py     every host-side path; nothing else may hardcode a home layout
+agent_box/runtime_bundle.py immutable package copies for running boxes
+agent_box/skills/      skills agent-box ships and installs (owned, checked in)
+agent_box/Containerfile the workspace image, with optional tool groups
+tests/                 unittest, no plugins
+```
+
+## Rules that are not negotiable
+
+**Semantic Versioning from 1.0.0.** Use SemVer: PATCH fixes bugs compatibly,
+MINOR adds backward-compatible functionality, and breaking changes to the
+documented public contract require MAJOR. Describe breaking changes and their
+upgrade path in release notes. Package versions and persisted schema versions
+are separate; see `docs/compatibility.md` for the public surface and formats.
+
+**Every public version upgrades directly to every later version.** Keep forward
+migrations, including across major releases; users never install intermediate
+packages. Before changing a persisted format or owned integration layout, assess
+migration impact, retain published fixtures, add the required conversion and
+test skipped versions, failure/retry and data preservation. Reject future schemas
+before parsing or writing; preserve the original before migration commits. Do
+not invent migrations for unpublished layouts. Running workspace runtimes stay
+immutable; adopting a new runtime may require an explicit stop/relaunch.
+
+**Paths come from `paths.py`.** Use `HOST_HOME` (passwd-derived), never
+`Path.home()`, `os.path.expanduser`, or `$HOME`. A poisoned environment must not
+be able to move a bind mount, a state directory or the container's home.
+
+**Off by default.** Anything that exposes a credential or widens what an agent
+can reach starts disabled. The exceptions are documented in the dataclass that
+defines them, with the reason.
+
+**Apply once after a package update.** `runtime.apply_config` is the single
+integration writer. Configuration commands apply explicit changes; the first
+host launch after a package update automatically migrates data and refreshes
+already configured integrations under a lock, recording the package identity
+only after success. Unchanged launches and read-only commands do not reapply.
+Rendered sessions never infer or rewrite unavailable host settings. Preserve
+user-owned content and opt-ins; keep `config apply` for manual edits and retry,
+and `uninstall` for removing owned integrations.
+
+On-demand Claude usage may renew and atomically save its OAuth credentials;
+this is authentication maintenance, not integration application. Status-line
+reads never renew tokens. Coordinate credential writes with Claude's locks.
+
+**Installation belongs to the installer.** uv/pipx own the command and shell
+PATH setup. agent-box never edits shell startup files or installer entry points.
+After upgrading the package, the next host launch refreshes integrations;
+run `agent-box uninstall` before removing the package through its installer.
+
+**agent-box owns its integrations.** An integration configured somewhere else,
+that the user has to assemble first, is not an integration. Settings live in
+`config.json`; skills are shipped in `agent_box/skills/` and installed by
+agent-box; the container gets a rendered, minimal artifact, never `config.json`
+itself.
+
+**Derived, not stored.** A fact that Git, GitHub or the tracker already owns is
+read back from there. Branch names come from the task's `ab/<id>-` namespace,
+the base branch from origin's default, the pull request from a head/base lookup,
+the lifecycle from the board's own columns. `.agent-box.json` names the tracker
+project and holds the allowed project configuration overrides. Nothing machine-readable is written into a tracker
+comment: a comment is a human journal, and lifecycle is read from the tracker's
+own fields.
+
+**Role ownership.** Plan sync may update tracker descriptions and comments through
+`agent-box tracker`, reading project files without changing them. The coordinator
+owns Git, lifecycle, dependencies and GitHub. Other roles keep their existing limits.
+
+**The coordinator accepts implementation.** A delegated worker reads its brief and
+the code, changes project files in the working tree, and answers in Markdown;
+a reviewer or scout reads and reports, changing nothing at all. The
+coordinator decides from that answer what to commit and what to record in the
+tracker and on GitHub. This is a contract, not credential isolation: a
+delegation runs either as a native subagent of the coordinator's own session or
+as a managed `codex exec` / `claude -p`, the first of which inherits the
+coordinator's workspace, `.git` and credentials, so the two backends
+deliberately share one contract rather than one of them acquiring private
+restrictions. Workers and scouts are therefore only launched (`workflow
+delegate`), never tracked: guards that only existed because the contract was
+wide belong deleted, not tightened. A reviewer round is still bound to its
+repository, project, task and scope by the descriptor workflow keeps beside the
+round's input, which is plain readable JSON and is deliberately not treated as
+unforgeable; a native reviewer's model and context are taken on trust.
+
+**Secrets travel by name.** `--env=NAME` (Podman inherits the value) for
+anything secret; `--env=NAME=VALUE` puts the value in an argv that `/proc`
+exposes to other processes. `notify.sync_credentials` and
+`runtime.sync_tracker_runtime` are the pattern for rendered credential files.
+
+**Never overwrite what a user owns.** Skill directories carry a marker; ones
+without it are the user's. Claude's `statusLine` slot is filled only when empty.
+Hook removal only ever touches agent-box's own commands.
+
+## Working in the code
+
+- **All text an agent may read must be functionally compact.** Skills, instructions,
+  handoffs, messages, errors, hints, CLI help and command output need enough context,
+  exact commands and necessary constraints to act without guessing; remove filler
+  and repetition without cryptic compression.
+- **Comments explain why, not what.** The existing docstrings state the decision
+  and the alternative that was rejected. Match that; do not add narration.
+- **Tests are the specification.** Every test's name and docstring says what
+  behaviour is being protected and why it would be wrong otherwise. A test that
+  restates the implementation is noise.
+- **Structural vs per-exec.** Anything in `container_lifetime_args` is part of
+  the box's identity: changing it recreates the box. Per-invocation values go
+  through `invocation_env`. Choose deliberately.
+- **Diagnostics are returned, not printed**, so both the launch path and
+  `agent-box config` can render them (`tracker_warnings` is the pattern).
+
+## Commands
+
+```bash
+python3 tests/run_suite.py              # full suite; isolated paths, no outer PTY
+python3 -m agent_box selftest                     # fast, no Podman
+uvx ruff check --select E4,E9,F agent_box/ tests/   # what CI lints
+python3 -m agent_box config show                  # inspect the live config, tokens redacted
+```
+
+The runner uses unittest discovery, temporary state/integration paths and piped
+stdio. For focused runs: `python3 tests/run_suite.py discover -s tests -p test_browser.py`.
+Test modules import each other by bare name, so keep discovery.
+
+## Gotchas
+
+- `tests/` must never touch the developer's real `~/.claude` or `~/.agents`.
+  Anything that calls `config_interactive` or `apply_config` has to patch
+  `runtime.CLAUDE_HOME`, `runtime.CODEX_HOME`, `runtime.AGENT_SKILLS_DIR`, `runtime.MANAGED_SKILLS_SOURCE`
+  and the credential paths. This has bitten before.
+- Module-level constants derived from `paths.py` (`AGENTS_DIR`, `TRACKER_RUNTIME_DIR`,
+  `CONTAINER_TRACKER_RUNTIME_DIR`) are resolved at import; tests patch them on `runtime`,
+  not on `paths`.
+- `tests/run_suite.py` and `selftest` drop every inherited `AGENT_BOX_*` variable,
+  so they pass inside a workspace box as is; a bare `python3 -m unittest` does not,
+  and reads the session's `AGENT_BOX_RUNTIME_CONFIG` instead of its fixtures.
+- The image label `io.agent-box.tools` records the built tool groups. A missing
+  label means *unknown*, not *empty* — never report it as drift.
+- Inside a workspace box the saved configuration is not mounted: `config apply`
+  then applies only the skills and profiles the rendered session snapshot
+  describes and leaves host-only sections (notifications, hooks, status line,
+  credentials, Claude links) alone; the global `agent-box config` menu
+  refuses because it edits a file that is not there.
+- `agent_box/skills/` contains short owned `ab-*` skills. Maintain them directly
+  and keep their command/role contracts consistent with the Python helpers.
+- `.gitignore` ignores `/skills/` at the repo root only — `agent_box/skills/` is
+  checked in on purpose.

agent_box_tool-1.0.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Release notes
+
+## 1.0.0
+
+First public release of **agent-box**, distributed on PyPI as `agent-box-tool`.
+The command remains `agent-box`; Python 3.11+ and Linux are required, with no
+Python runtime dependencies. Workspace containers require rootless Podman 5+.
+
+- Run Claude Code and Codex CLI in reusable per-project workspaces, with
+  detachable sessions, selected host mounts and opt-in credential forwarding.
+- Configure owned integrations, skills, native agent profiles and portable
+  tracker/workflow support from the built-in configuration interface.
+- Install through uv tool or pipx from PyPI or the public Git repository.
+- Use SemVer and direct forward data migrations across all later releases,
+  including major versions. This release establishes the first supported
+  public data formats and regression fixtures.
+- Refresh configured integrations automatically on the first host launch after
+  a package update. Failed application remains retryable; `config apply` is
+  available for manual edits and recovery.
+- Preserve running workspaces on their immutable runtime until explicit
+  stop/relaunch. Package upgrades preserve saved choices and workspace data.
+
+See [installation](docs/installation.md) and
+[compatibility](docs/compatibility.md) for the supported upgrade boundaries.
+AUR packaging is separate follow-up work.

agent_box_tool-1.0.0/LICENSE

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

agent_box_tool-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include AGENTS.md CHANGELOG.md
+recursive-include docs *.md
+recursive-include tests *.py *.json
+recursive-include tools *.py

agent_box_tool-1.0.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: agent-box-tool
+Version: 1.0.0
+Summary: Run coding agents in rootless Podman workspace boxes
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rus364/agent-box
+Project-URL: Documentation, https://github.com/rus364/agent-box/blob/main/docs/README.md
+Project-URL: Repository, https://github.com/rus364/agent-box
+Project-URL: Issues, https://github.com/rus364/agent-box/issues
+Project-URL: Changelog, https://github.com/rus364/agent-box/blob/main/CHANGELOG.md
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<div align="center">
+
+# agent-box
+
+**Run Claude Code and Codex CLI in isolated, reusable Podman workspaces.**
+
+One project. One shared container. Your agents, shell, tools, state, and detachable sessions stay together without giving the container your whole host.
+
+[![CI](https://github.com/rus364/agent-box/actions/workflows/ci.yml/badge.svg)](https://github.com/rus364/agent-box/actions/workflows/ci.yml)
+![Linux](https://img.shields.io/badge/platform-Linux-informational)
+![Podman](https://img.shields.io/badge/runtime-Podman-892CA0)
+![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+</div>
+
+---
+
+## Why agent-box?
+
+AI coding agents are useful, but running them directly on your workstation
+gives them the same files, credentials, tools and processes that you have.
+agent-box runs Claude Code and Codex CLI inside a rootless Podman container
+while keeping the workflow close to local development:
+
+- **Workspace isolation** — only the project root and the mounts you ask for are exposed.
+- **One box per project** — Claude, Codex and `agent-box shell` share the same container.
+- **Same paths as the host** — `/home/you/code/project` is `/home/you/code/project` inside the box too.
+- **Persistent agent state** — logins, settings and history stay in your host's `~/.claude` and `~/.codex`.
+- **Detachable sessions** — sessions run under tmux and survive a closed terminal or a dropped SSH connection.
+- **Nothing exposed by accident** — every credential, host directory and optional capability is a switch you turn on.
+
+> [!IMPORTANT]
+> A workspace box is one trust boundary. Claude, Codex, shells, hooks and
+> daemons inside the same box share the same Unix user and PID namespace.
+
+## Requirements
+
+- Linux
+- Python 3.11 or newer (standard library only)
+- Rootless Podman 5.0 or newer — agent-box does not fall back to Docker
+- Git
+- Optional: `gh`, to pass a GitHub token into the box
+
+agent-box checks all of this before starting a box and prints the command that
+fixes anything missing. Details: [Installation](docs/installation.md#requirements).
+
+## Installation
+
+```bash
+# 1. Install from PyPI.
+uv tool install agent-box-tool
+uv tool update-shell   # if the installer reports PATH setup is needed
+
+# 2. Reopen the shell if PATH changed, then configure integrations.
+agent-box config
+```
+
+The distribution is `agent-box-tool`; the command stays `agent-box`.
+[pipx, public Git and editable installs](docs/installation.md) are also supported.
+
+3. Log in with `claude` and `codex` on the host; agent-box reuses those logins.
+4. Start a session in your project. The workspace image is built automatically
+   the first time, which takes a few minutes once.
+
+```bash
+cd ~/code/my-project
+agent-box claude          # or: agent-box codex
+```
+
+Shell completion, updating and uninstalling are covered in
+[Installation](docs/installation.md).
+
+## Quick start
+
+```bash
+agent-box                 # the default agent (Claude unless you choose Codex)
+agent-box shell           # a shell in this project's box
+agent-box attach          # reattach a detached session (detach with Ctrl-\ d)
+agent-box stop            # end the box and every session in it
+agent-box --host codex    # run the host's CLI directly, without a container
+agent-box doctor          # check the box and its integrations
+```
+
+Options before the agent apply to one launch, for example
+`agent-box --mount ~/specs:ro --env DATABASE_URL claude`. See
+[Usage](docs/usage.md) for all of them.
+
+## How it works
+
+```mermaid
+flowchart LR
+    Host["Host workspace"] --> Launcher["agent-box"]
+    Launcher --> Box["Rootless Podman workspace box"]
+
+    Box --> Claude["Claude Code"]
+    Box --> Codex["Codex CLI"]
+    Box --> Shell["Shell"]
+
+    Claude --> Tmux["tmux sessions"]
+    Codex --> Tmux
+    Shell --> Tmux
+
+    State["~/.claude / ~/.codex"] -. host-backed state .-> Box
+    Project["Project root\nsame absolute path"] -. explicit bind mount .-> Box
+```
+
+**Workspace box.** The first command in a project creates its box; later
+commands join it. A different project gets a different box, and a box with no
+workload left exits and is removed. The box mounts the Git top level of the
+current directory and your agent state; any other host path, credential or
+device only when you enable it.
+
+**Host mode.** `--host` runs your installed `claude` or `codex` directly, with
+your own environment and credentials. Tracker, workflow and model routing
+behave the same; container-only features such as mounts and the agent browser
+do not apply.
+
+**Configuration.** Built-in defaults, then your global
+`~/.config/agent-box/config.json`, then the repository's `.agent-box.json`.
+`agent-box config` edits settings and applies integrations. The first host launch
+after a package update refreshes configured integrations automatically; unchanged
+launches leave them alone. See [compatibility and upgrades](docs/compatibility.md).
+
+## Documentation
+
+| Page | What it covers |
+| --- | --- |
+| [Installation](docs/installation.md) | Requirements, setup, shell completion, updating, uninstalling |
+| [Usage](docs/usage.md) | Sessions, options, mounts, environment, host mode, usage limits and status line |
+| [Configuration](docs/configuration.md) | The menu, defaults, project configuration, `config ai` |
+| [Workspace image](docs/image.md) | Included tools, optional groups, building and refreshing |
+| [Security model](docs/security.md) | What a box can reach and how it is hardened |
+| [Integrations](docs/integrations/README.md) | Tracker and workflow, browser, k3s, Telegram, credentials and more — all optional |
+| [Troubleshooting](docs/troubleshooting.md) | Diagnostics, common problems, known limitations |
+
+The full index, including design records for contributors, is in
+[docs/](docs/README.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agent_box_tool-1.0.0/README.md

@@ -0,0 +1,142 @@
+<div align="center">
+
+# agent-box
+
+**Run Claude Code and Codex CLI in isolated, reusable Podman workspaces.**
+
+One project. One shared container. Your agents, shell, tools, state, and detachable sessions stay together without giving the container your whole host.
+
+[![CI](https://github.com/rus364/agent-box/actions/workflows/ci.yml/badge.svg)](https://github.com/rus364/agent-box/actions/workflows/ci.yml)
+![Linux](https://img.shields.io/badge/platform-Linux-informational)
+![Podman](https://img.shields.io/badge/runtime-Podman-892CA0)
+![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+</div>
+
+---
+
+## Why agent-box?
+
+AI coding agents are useful, but running them directly on your workstation
+gives them the same files, credentials, tools and processes that you have.
+agent-box runs Claude Code and Codex CLI inside a rootless Podman container
+while keeping the workflow close to local development:
+
+- **Workspace isolation** — only the project root and the mounts you ask for are exposed.
+- **One box per project** — Claude, Codex and `agent-box shell` share the same container.
+- **Same paths as the host** — `/home/you/code/project` is `/home/you/code/project` inside the box too.
+- **Persistent agent state** — logins, settings and history stay in your host's `~/.claude` and `~/.codex`.
+- **Detachable sessions** — sessions run under tmux and survive a closed terminal or a dropped SSH connection.
+- **Nothing exposed by accident** — every credential, host directory and optional capability is a switch you turn on.
+
+> [!IMPORTANT]
+> A workspace box is one trust boundary. Claude, Codex, shells, hooks and
+> daemons inside the same box share the same Unix user and PID namespace.
+
+## Requirements
+
+- Linux
+- Python 3.11 or newer (standard library only)
+- Rootless Podman 5.0 or newer — agent-box does not fall back to Docker
+- Git
+- Optional: `gh`, to pass a GitHub token into the box
+
+agent-box checks all of this before starting a box and prints the command that
+fixes anything missing. Details: [Installation](docs/installation.md#requirements).
+
+## Installation
+
+```bash
+# 1. Install from PyPI.
+uv tool install agent-box-tool
+uv tool update-shell   # if the installer reports PATH setup is needed
+
+# 2. Reopen the shell if PATH changed, then configure integrations.
+agent-box config
+```
+
+The distribution is `agent-box-tool`; the command stays `agent-box`.
+[pipx, public Git and editable installs](docs/installation.md) are also supported.
+
+3. Log in with `claude` and `codex` on the host; agent-box reuses those logins.
+4. Start a session in your project. The workspace image is built automatically
+   the first time, which takes a few minutes once.
+
+```bash
+cd ~/code/my-project
+agent-box claude          # or: agent-box codex
+```
+
+Shell completion, updating and uninstalling are covered in
+[Installation](docs/installation.md).
+
+## Quick start
+
+```bash
+agent-box                 # the default agent (Claude unless you choose Codex)
+agent-box shell           # a shell in this project's box
+agent-box attach          # reattach a detached session (detach with Ctrl-\ d)
+agent-box stop            # end the box and every session in it
+agent-box --host codex    # run the host's CLI directly, without a container
+agent-box doctor          # check the box and its integrations
+```
+
+Options before the agent apply to one launch, for example
+`agent-box --mount ~/specs:ro --env DATABASE_URL claude`. See
+[Usage](docs/usage.md) for all of them.
+
+## How it works
+
+```mermaid
+flowchart LR
+    Host["Host workspace"] --> Launcher["agent-box"]
+    Launcher --> Box["Rootless Podman workspace box"]
+
+    Box --> Claude["Claude Code"]
+    Box --> Codex["Codex CLI"]
+    Box --> Shell["Shell"]
+
+    Claude --> Tmux["tmux sessions"]
+    Codex --> Tmux
+    Shell --> Tmux
+
+    State["~/.claude / ~/.codex"] -. host-backed state .-> Box
+    Project["Project root\nsame absolute path"] -. explicit bind mount .-> Box
+```
+
+**Workspace box.** The first command in a project creates its box; later
+commands join it. A different project gets a different box, and a box with no
+workload left exits and is removed. The box mounts the Git top level of the
+current directory and your agent state; any other host path, credential or
+device only when you enable it.
+
+**Host mode.** `--host` runs your installed `claude` or `codex` directly, with
+your own environment and credentials. Tracker, workflow and model routing
+behave the same; container-only features such as mounts and the agent browser
+do not apply.
+
+**Configuration.** Built-in defaults, then your global
+`~/.config/agent-box/config.json`, then the repository's `.agent-box.json`.
+`agent-box config` edits settings and applies integrations. The first host launch
+after a package update refreshes configured integrations automatically; unchanged
+launches leave them alone. See [compatibility and upgrades](docs/compatibility.md).
+
+## Documentation
+
+| Page | What it covers |
+| --- | --- |
+| [Installation](docs/installation.md) | Requirements, setup, shell completion, updating, uninstalling |
+| [Usage](docs/usage.md) | Sessions, options, mounts, environment, host mode, usage limits and status line |
+| [Configuration](docs/configuration.md) | The menu, defaults, project configuration, `config ai` |
+| [Workspace image](docs/image.md) | Included tools, optional groups, building and refreshing |
+| [Security model](docs/security.md) | What a box can reach and how it is hardened |
+| [Integrations](docs/integrations/README.md) | Tracker and workflow, browser, k3s, Telegram, credentials and more — all optional |
+| [Troubleshooting](docs/troubleshooting.md) | Diagnostics, common problems, known limitations |
+
+The full index, including design records for contributors, is in
+[docs/](docs/README.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agent_box_tool-1.0.0/agent_box/.containerignore

@@ -0,0 +1,2 @@
+*
+!nested_podman.py