diff --git a/.agents/skills/dependencies-management/SKILL.md b/.agents/skills/dependencies-management/SKILL.md
index 4f9c72d..5fb579e 100644
--- a/.agents/skills/dependencies-management/SKILL.md
+++ b/.agents/skills/dependencies-management/SKILL.md
@@ -1,12 +1,12 @@
 ---
   name: dependencies-management
-  description: instructions for updating and managing project dependencies (including Github actions).
+  description: instructions for updating and managing project dependencies (including Github actions and pre-commit hooks).
 ---
 # Dependencies Management
 
 ## Update Dependencies
 
-Instructions to update project dependencies (including Github actions used by CI workflows).
+Instructions to update project dependencies (including Github actions and pre-commit hooks).
 
 ### 1. Prepare the branch
 
@@ -32,7 +32,18 @@ prompt: What is the latest release tag for this GitHub action?
 
 In each case update the version pin to any more recent release. **Preserve the existing pinning style**, so if the current pin is a specific version such as `@v3.0.1`, update to the full latest version string, whilst if it's a major-version tag such as `@v4`, update to any new major-version tag (if the project no longer publishes a major-version tag then switch to the full semver).
 
-### 4. Test
+### 4. Update pre-commit hook versions
+
+For each `repo:` entry in `.pre-commit-config.yaml`, retrieve the latest release tag by fetching the releases page with WebFetch:
+
+```
+url:    https://github.com/<owner>/<repo>/releases/latest
+prompt: What is the latest release tag for this pre-commit hook?
+```
+
+In each case update the `rev:` pin to any more recent release. **Preserve the existing pinning style**, so if the current pin is a specific version such as `v6.0.0`, update to the full latest version string, whilst if it's a major-version tag such as `@v4`, update to any new major-version tag (if the project no longer publishes a major-version tag then switch to the full semver).
+
+### 5. Test
 
 Run the test suite:
 ```bash
@@ -40,10 +51,10 @@ uv run pytest -v
 ```
 
 **Interpret local test results:**
-- All tests pass and no raised warning is fixable (see *Fixable warnings* section below) → go to step 6 to raise PR.
-- Any test failure or a fixable warning raised → proceed to step 5 to fix.
+- All tests pass and no raised warning is fixable (see *Fixable warnings* section below) → go to step 7 to raise PR.
+- Any test failure or a fixable warning raised → proceed to step 6 to fix.
 
-### 5. Fix
+### 6. Fix
 Any failing tests and fixable warnings will likely have their origin in changes to the dependencies. To provide support for the latest dependencies MAKE REVISIONS to the code base to fix:
 - code causing tests to fail.
 - all fixable warnings (see *Fixable warnings* section below).
@@ -62,7 +73,7 @@ IMPORTANT: in this step you should not run the full test suite, rather validate
 pytest tests/test_module.py::test_name
 ```
 
-### 6. Raise PR
+### 7. Raise PR
 
 Once local tests pass, commit all changes to the branch and raise a PR.
 
@@ -73,21 +84,21 @@ Once local tests pass, commit all changes to the branch and raise a PR.
 - **label**: Add the 'dependencies' label to the PR.
 - otherwise comply with the package's 'create-pr' skill.
 
-### 7. Subscribe to PR activity
+### 8. Subscribe to PR activity
 
 By raising the PR a GitHub CI workflow will be triggered. Subscribe to the raised PR's activity.
 
-Proceed to step 8 when you receive an event indicating that the triggered workflow has completed.
+Proceed to step 9 when you receive an event indicating that the triggered workflow has completed.
 
-### 8. Inspect CI results
+### 9. Inspect CI results
 
 The CI workflow will have run the full test suite against a matrix of OS and Python versions. Use `mcp__github__pull_request_read` with the `get_check_runs` method to read check statuses for all matrix jobs.
 
 **Interpret CI test results:**
-- All checks green → proceed to step 11.
-- Any check red → proceed to step 9.
+- All checks green → proceed to step 12.
+- Any check red → proceed to step 10.
 
-### 9. Fix tests for specific OS/Python configuration
+### 10. Fix tests for specific OS/Python configuration
 
 Use the information read from `get_check_runs` to identify any OS/python version configurations for which the test suite has failed.
 
@@ -104,18 +115,18 @@ Run the test suite to identify failing tests. For example:
 uv run --isolated --python 3.12 python pytest --ignore=tests/test_yahoo.py -v
 ```
 
-Then find fixes for the failing tests by following step 5.
+Then find fixes for the failing tests by following step 6.
 
-Finally commit the necessary changes to your *original* branch (to which previous commits were made). This will trigger the CI on the PR re-run. Return to step 8 (inspect CI results).
+Finally commit the necessary changes to your *original* branch (to which previous commits were made). This will trigger the CI on the PR re-run. Return to step 9 (inspect CI results).
 
-### 10. Fallback: raise an issue
+### 11. Fallback: raise an issue
 
 ONLY if any test failures cannot be resolved, raise an issue that references the PR and details:
 - the failing tests
 - any fixes already attempted
 - any suggested next steps.
 
-### 11. Tidy up
+### 12. Tidy up
 
 Perform the following 'tidy up' actions:
 - Call `mcp__github__unsubscribe_pr_activity` to unscubscribe from the PR activity.
diff --git a/.agents/skills/update-agents-md/SKILL.md b/.agents/skills/update-agents-md/SKILL.md
index f4232f1..8ca58eb 100644
--- a/.agents/skills/update-agents-md/SKILL.md
+++ b/.agents/skills/update-agents-md/SKILL.md
@@ -13,6 +13,7 @@ Update the 'Repository Layout' section to reflect the current layout. Remove all
     - all files named `__init__.py`
 - do not include files and/or folders under the following directories (but do include the folders listed here):
     - @tests/resources
+    - @examples
 List all folders before any files for any given hierarchal level.
 If the purpose of a file or directory is not reasonably evident from its name then include a minimalist comment offering a top-line explanation.
 The comment should:
diff --git a/AGENTS.md b/AGENTS.md
index 09c75c8..8b089ad 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,7 +22,58 @@ See @pyproject.toml for project metadata and dependencies.
 ### Repository Layout
 
 ```
-TODO
+beanahead/
+├── .agents/                            # instructions for LLM coding agents
+│   └── skills/                         # skills for LLM coding agents
+│       ├── create-pr/
+│       │   └── SKILL.md
+│       ├── dependencies-management/
+│       │   └── SKILL.md
+│       └── update-agents-md/
+│           └── SKILL.md
+├── .github/
+│   ├── workflows/
+│   │   ├── build-test.yml
+│   │   ├── draft-release-notes.yml
+│   │   └── release.yml
+│   └── release-drafter.yml
+├── examples/                           # example files referred to by docs
+├── src/
+│   └── beanahead/
+│       ├── plugins/
+│       │   └── rx_txn_plugin.py
+│       ├── scripts/
+│       │   └── cli.py
+│       ├── config.py
+│       ├── errors.py
+│       ├── expired.py
+│       ├── reconcile.py
+│       ├── rx_txns.py
+│       └── utils.py
+├── tests/
+│   ├── resources/                      # Static test resource files
+│   ├── cmn.py                          # Shared test helper functions
+│   ├── conftest.py
+│   ├── test_config.py
+│   ├── test_errors.py
+│   ├── test_expired.py
+│   ├── test_init.py
+│   ├── test_plugins.py
+│   ├── test_reconcile.py
+│   ├── test_rx_txns.py
+│   └── test_utils.py
+├── .pre-commit-config.yaml
+├── .python-version
+├── AGENTS.md
+├── CLAUDE.md
+├── LICENSE.txt
+├── MANIFEST.in
+├── README.md
+├── pyproject.toml
+├── pytest.ini
+├── requirements.txt
+├── ruff.toml
+└── uv.lock
 ```
 
 ## Technology Stack