Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion .github/workflows/python-package.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,12 @@ jobs:
- run: python -m ruff format --check .
- run: python tools/differential_correction.py --verify
- run: python -m build --no-isolation
- run: python tools/verify_wheel_environment.py
- name: Test the built wheel
shell: bash
run: |
python -m pip install --force-reinstall --no-deps dist/codex32-*.whl
python -c "import codex32, pathlib; assert 'site-packages' in pathlib.Path(codex32.__file__).parts"
python -m pytest -q

compatibility:
runs-on: ubuntu-latest
Expand Down
55 changes: 21 additions & 34 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,35 +20,27 @@ concise, with the outcome, relevant evidence, and any remaining limitations.
## Project structure

Production code lives in `src/codex32/`; keep modules narrow and do not duplicate
domain logic in `cli.py` or `profiles/`. Tests live in `tests/test_*.py`, with
domain logic in `cli.py`. Tests live in `tests/test_*.py`, with
frozen external vectors under `tests/data/`. Durable documentation is grouped
under `docs/user/`, `docs/developer/`, and `docs/security/`. Local plans and
unfinished reports belong in the ignored `docs/planning/` directory. `tools/`
contains offline verification utilities.

## Development and verification

Use the existing virtual environment when available. Python 3.10 is the minimum;
the supported range is Python 3.10 through 3.15. Install development
dependencies only when needed:
`python -m pip install -e '.[dev]'`. Run the CLI with `codex32 --help`.

Choose checks according to the changed behavior:

- Runtime changes: run affected pytest tests, Ruff lint and formatting checks,
and `python -m mypy src/codex32` when types or source code change.
- Changes spanning modules or security boundaries: run `python -m pytest -q`
and `python -O -m pytest -q`; use the relevant differential tools for changes
to correction or wallet derivation.
- Packaging or release changes: run `python -m build` and
`python -m twine check dist/*` in addition to affected checks.
- Documentation or agent-configuration changes: inspect the diff, check links
and configuration syntax as applicable; do not run application tests solely
for prose or instruction edits.

Use `python -m ruff check .` and `python -m ruff format --check .` for Python
style checks. Once applicable checks pass, repeat or broaden them only for a new
change, failure, or unresolved concern. Report checks that could not run and
Before setting up an environment or choosing checks, read the setup and check
list in `CONTRIBUTING.md`. Use the existing virtual environment when available.
Pick checks by what changed:

- Runtime changes: affected pytest tests, Ruff, and mypy.
- Changes spanning modules or security boundaries: the full suite, also under
`python -O`, plus the differential tools for correction or wallet derivation.
- Packaging or release changes: the build and `twine check` steps as well.
- Documentation or agent-configuration changes: inspect the diff and check links
and syntax; do not run application tests for prose edits alone.

Once applicable checks pass, repeat or broaden them only for a new change,
failure, or unresolved concern. Report checks that could not run and
pre-existing failures accurately; do not claim unverified success.

## Reviewability and style
Expand All @@ -61,8 +53,7 @@ avoid comments or tests that restate the implementation. Add or update concise
docstrings when changing public behavior. Write codex32 in lowercase except
when referring to the Codex32 Book.

Keep the installed package below 5,200 logical review lines, as enforced by the
existing test. New dependencies, public API signature or return-shape changes,
Respect the review-line budgets in `CONTRIBUTING.md`. New dependencies, public API signature or return-shape changes,
and lint suppressions require user authorization; an explicit request can
already provide that authorization.

Expand All @@ -86,13 +77,9 @@ Resolve scope questions from the changed code and the invariants first. Ask only
if a material security decision remains unclear; identify the decision rather
than stopping on general uncertainty. Ask before running a recommended security review.

Follow `docs/developer/AI_POLICY.md` for contributions and `SECURITY.md` for
private vulnerability reporting. Local edits, checks, and atomic commits are
allowed; do not automatically push, open pull requests, write replies, contact
maintainers, or claim authorship. A human publishes contributions. Never commit
to master or push to an open pull request branch without explicit user direction.

When asked to commit, keep commits focused and independently passing unless the
user explicitly requests a combined commit. Use an imperative subject of at
most 50 characters, followed by rationale, security implications when relevant,
and validation. Use `refs #123` or `fixes #123` when applicable.
Before committing, opening a pull request, or writing an issue, pull request,
or review comment, read `docs/developer/AI_POLICY.md` and the commit and pull
request sections of `CONTRIBUTING.md`; they decide authorship, commit messages,
and who publishes. Local edits, checks, and focused commits are allowed. Never
commit to master or push to an open pull request branch without explicit user
direction. Follow `SECURITY.md` for private vulnerability reporting.
14 changes: 6 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,23 +47,21 @@ On Windows, activate the environment with `.venv\Scripts\activate` instead.

The installed commands are `codex32` and `ms32`.

`codex32` checks, corrects, recovers, and derives shares for registered or opaque
application prefixes. `ms32` additionally creates Bitcoin master-seed backups
`codex32` checks, corrects, recovers, and derives shares for any application
prefix. `ms32` additionally creates Bitcoin master-seed backups
and provides key and wallet setup.

BIP39 worksheet profiles are supported for existing-backup recovery but are
[not recommended for creating backups](https://secretcodex32.com/docs/index.html).
Powerful correction searches, including recovery of genuinely unreadable
characters, require interactive confirmation.

## Start here

Start Bitcoin Core 32 or newer with local RPC enabled. codex32 detects and
reports the local Bitcoin Core network. To practice with Bitcoin-Qt on signet,
start it with:
Start Bitcoin Core 32 or newer with local RPC enabled. codex32 uses the
network `bitcoin-cli` is configured for and reports it. To practice on signet,
add `signet=1` to `bitcoin.conf`, then start Bitcoin-Qt with:

```bash
bitcoin-qt -signet -server
bitcoin-qt -server
```

Then run:
Expand Down
Loading
Loading