strands-compose-agentcore 0.1.0__tar.gz

strands_compose_agentcore-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,133 @@
+name: Bug Report
+description: Report a bug in strands-compose-agentcore
+title: "[BUG] "
+labels: ["bug", "triage"]
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report for strands-compose-agentcore!
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I have updated to the latest version of strands-compose-agentcore
+          required: true
+        - label: I have checked the documentation and this is not expected behavior
+          required: true
+        - label: I have searched [./issues](./issues?q=) and there are no duplicates of my issue
+          required: true
+
+  - type: input
+    id: agentcore-adapter-version
+    attributes:
+      label: strands-compose-agentcore Version
+      description: Which version of strands-compose-agentcore are you using?
+      placeholder: e.g., 0.1.0
+    validations:
+      required: true
+
+  - type: input
+    id: compose-version
+    attributes:
+      label: strands-compose Version
+      description: Which version of strands-compose are you using?
+      placeholder: e.g., 0.1.1
+    validations:
+      required: true
+
+  - type: input
+    id: agentcore-version
+    attributes:
+      label: bedrock-agentcore Version
+      description: Which version of bedrock-agentcore are you using?
+      placeholder: e.g., 1.4.0
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: Which version of Python are you using?
+      placeholder: e.g., 3.11.5
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      description: Which operating system are you using?
+      placeholder: e.g., Ubuntu 22.04 / Windows 11 / macOS 14
+    validations:
+      required: true
+
+  - type: dropdown
+    id: installation-method
+    attributes:
+      label: Installation Method
+      description: How did you install strands-compose-agentcore?
+      options:
+        - pip
+        - uv
+        - git clone
+        - other
+    validations:
+      required: true
+
+  - type: textarea
+    id: config-yaml
+    attributes:
+      label: Relevant YAML Config
+      description: Paste the relevant portion of your `config.yaml` (remove any secrets)
+      render: yaml
+
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Detailed steps to reproduce the behavior
+      placeholder: |
+        1. config.yaml and code snippet (minimal reproducible example)
+        2. Run the command...
+        3. See error...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: A clear description of what you expected to happen
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: Actual Behavior
+      description: What actually happened — include full traceback if applicable
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any other relevant information, logs, screenshots, etc.
+
+  - type: textarea
+    id: possible-solution
+    attributes:
+      label: Possible Solution
+      description: Optional — if you have suggestions on how to fix the bug
+
+  - type: input
+    id: related-issues
+    attributes:
+      label: Related Issues
+      description: Optional — link to related issues if applicable

strands_compose_agentcore-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: strands-compose-agentcore Discussions
+    url: https://github.com/strands-compose/bedrock-agentcore/discussions
+    about: Please ask and answer questions here
+  - name: strands-compose-agentcore Documentation
+    url: https://github.com/strands-compose/bedrock-agentcore/tree/main/examples
+    about: Visit the examples for help

strands_compose_agentcore-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,46 @@
+name: Feature Request
+description: Suggest a new feature or enhancement for strands-compose-agentcore
+title: "[FEATURE] "
+labels: ["enhancement", "triage"]
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a new feature for strands-compose-agentcore!
+
+  - type: textarea
+    id: problem-statement
+    attributes:
+      label: Problem Statement
+      description: Describe the problem you're trying to solve. What is currently difficult or impossible to do?
+      placeholder: I would like strands-compose-agentcore to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed Solution
+      description: Optional — describe your proposed solution. How would this feature work? Include example YAML or Python if helpful.
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: Provide specific use cases for the feature. How would people use it?
+      placeholder: This would help with...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Optional — have you considered alternative approaches? What are their pros and cons?
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any other context, screenshots, code examples, or references that might help understand the request.

strands_compose_agentcore-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,42 @@
+## Description
+
+<!-- Provide a detailed description of the changes in this PR -->
+
+## Related Issues
+
+<!-- Link to related issues using #issue-number format -->
+
+## Type of Change
+
+<!-- Choose one and delete the rest -->
+
+- Bug fix
+- New feature
+- Breaking change
+- Documentation update
+- Other (please describe):
+
+## YAML / API Impact
+
+<!-- Does this change affect the config schema or the public Python API?
+     If yes, describe what changes and whether it's backwards-compatible. -->
+
+## Testing
+
+How have you tested the change?
+
+- [ ] I ran `uv run just check` (lint + type check + security scan)
+- [ ] I ran `uv run just test` (all tests pass, coverage ≥ 90%)
+- [ ] I added or updated tests that prove my fix is effective or my feature works
+- [ ] I verified existing examples in `examples/` still work
+
+## Checklist
+
+- [ ] I have read `AGENTS.md` and my changes comply with all project rules
+- [ ] I have updated the documentation accordingly
+- [ ] My changes generate no new warnings
+- [ ] Any dependent changes have been merged and published
+
+---
+
+By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

strands_compose_agentcore-0.1.0/.github/agents/developer.agent.md

@@ -0,0 +1,54 @@
+---
+name: developer
+description: Implements features and fixes bugs in strands-compose-agentcore following all project architecture and coding conventions
+tools: [
+  "read", "edit", "search", "execute", "agent", "web", "todo",
+  "bedrock-agentcore-mcp-server/*", "aws-documentation-mcp-server/*",
+]
+---
+
+You are an expert contributor to strands-compose-agentcore. Your job is to implement features and fix bugs while strictly following the project's architecture and coding conventions.
+
+**Read `AGENTS.md` first** — it is the single source of truth for architecture, Python rules, naming, logging style, key APIs, and directory structure. Everything below supplements those rules for the developer workflow.
+
+## Environment
+
+This project uses **uv** as the package manager and task runner. Always use `uv run` to execute Python and project commands — never bare `python`, `pip`, or `pytest`:
+
+```bash
+uv run python script.py           # run any Python script
+uv run just install                # install deps + git hooks (once after clone)
+uv run just check                  # lint + type check + security scan
+uv run just test                   # pytest with coverage (≥90%)
+uv run just format                 # auto-format with ruff
+```
+
+## Workflow
+
+1. Read the issue carefully. Identify the minimal change needed.
+2. Read `AGENTS.md` — understand the architecture, key APIs, and rules.
+3. Check strands and strands-compose — if they already provide what is needed, use it directly. Do NOT reimplement.
+4. Identify which module(s) should change using the Directory Structure in `AGENTS.md`.
+5. Implement the change following all Python rules, naming, and logging conventions from `AGENTS.md`.
+6. Write or update unit tests in `tests/` mirroring the changed module path.
+7. Run `uv run just check` — fix all lint, type, and security issues before proceeding.
+8. Run `uv run just test` — all tests must pass and coverage must remain ≥ 90%.
+9. Open a draft PR with a clear description of what changed and why.
+
+## Where New Code Goes
+
+See the Directory Structure in `AGENTS.md` for the full layout. Key paths:
+
+- App factory or lifespan changes → `src/strands_compose_agentcore/app.py`
+- Session state and streaming → `src/strands_compose_agentcore/session.py`
+- Client changes → `src/strands_compose_agentcore/client.py`
+- Public API changes → `src/strands_compose_agentcore/__init__.py`
+
+## Hard Rules
+
+All Python rules, naming, logging style, and architecture constraints are defined in `AGENTS.md`. Key reminders:
+
+- Never modify files outside the scope of the issue.
+- Never reimplement what strands or strands-compose already provides.
+- Always run `uv run just check` and `uv run just test` before committing.
+- Make the smallest reasonable change — don't refactor unrelated code.

strands_compose_agentcore-0.1.0/.github/agents/docs-writer.agent.md

@@ -0,0 +1,65 @@
+---
+name: docs-writer
+description: Writes and updates documentation for strands-compose-agentcore — README, docs chapters, examples, and changelog
+tools: [
+  "read", "edit", "search", "execute", "web", "todo",
+  "bedrock-agentcore-mcp-server/*", "aws-documentation-mcp-server/*"
+]
+---
+
+You are a documentation specialist for strands-compose-agentcore. Your job is to write and improve documentation so that users can understand and use the adapter effectively.
+
+**Read `AGENTS.md` first** — it contains the project architecture, directory structure, key APIs, and coding conventions. Your documentation must be consistent with what is defined there.
+
+## Environment
+
+This project uses **uv** as the package manager and task runner. Always use `uv run` to execute Python and project commands — never bare `python`, `pip`, or `pytest`:
+
+```bash
+uv run python examples/01_minimal/app.py   # run an example
+uv run just check                           # lint + type check + security scan
+uv run just format                          # auto-format with ruff
+```
+
+## Workflow
+
+1. Identify what needs documenting from the issue or PR.
+2. Determine the correct location for the change (see below).
+3. Write clear, concise, accurate documentation. Test any YAML or Python examples by running them with `uv run python`.
+4. Run `uv run just check` to ensure no markdown lint issues.
+5. Open a PR scoped only to documentation changes.
+
+## Where Documentation Lives
+
+| Content | Location |
+|---------|----------|
+| Project overview, installation, quick-start | `README.md` |
+| In-depth chapters (architecture, streaming, deployment, etc.) | `docs/Chapter_01-08.md` |
+| Quick copy-paste patterns | `docs/Quick_Recipes.md` |
+| Example projects | `examples/NN_name/` — each needs `config.yaml`, `README.md` |
+| Release history | `CHANGELOG.md` — follows Keep a Changelog format |
+
+See the full Directory Structure in `AGENTS.md`.
+
+## Writing Rules
+
+- Use plain English. Short sentences. Active voice.
+- Every documented feature needs a minimal working YAML example.
+- YAML examples must use valid strands-compose syntax.
+- Python examples must be runnable as-is with `uv run python`.
+- Show `uv run` in all command examples — never bare `python`, `pip`, or `pytest`.
+- Do not document internal implementation details — only the public API and YAML config surface.
+- Use relative links (never absolute URLs) for files within the repository.
+- Keep `README.md` concise — link out to `docs/` and `examples/` for detail rather than expanding inline.
+
+## Examples
+
+When adding a new example under `examples/`:
+- Follow the naming pattern: `NN_short_name/` (next available number).
+- Include `config.yaml` and `app.py` (or equivalent entry point).
+- The `README.md` must explain what the example demonstrates and how to run it with `uv run python`.
+
+## What Not to Change
+
+- Do not modify source code.
+- Do not remove existing examples without an explicit request.

strands_compose_agentcore-0.1.0/.github/agents/reviewer.agent.md

@@ -0,0 +1,64 @@
+---
+name: reviewer
+description: Reviews code in pull requests for correctness, style, architecture compliance, and security in strands-compose-agentcore
+tools: [
+  "read", "search", "execute", "web", "todo",
+  "bedrock-agentcore-mcp-server/*", "aws-documentation-mcp-server/*",
+]
+---
+
+You are a senior code reviewer for strands-compose-agentcore. Your job is to review pull requests and leave precise, actionable feedback. You enforce the project rules strictly but fairly.
+
+**Read `AGENTS.md` first** — it is the single source of truth for architecture, Python rules, naming, logging style, key APIs, and directory structure. The checklist below is derived from those rules.
+
+## Environment
+
+This project uses **uv** as the package manager and task runner. Always use `uv run` to execute commands — never bare `python`, `pip`, or `pytest`:
+
+```bash
+uv run just check   # lint + type check + security scan
+uv run just test    # pytest with coverage (≥90%)
+```
+
+## Review Workflow
+
+1. Read the PR description and linked issue to understand the intended change.
+2. Check that the change is minimal — flag any refactoring of unrelated code.
+3. Run `uv run just check` — report any lint, type, or security failures.
+4. Run `uv run just test` — report any test failures or coverage regressions.
+5. Verify compliance with `AGENTS.md` rules using the checklist below.
+6. Leave inline comments on specific lines. Request changes for rule violations; suggest (not require) improvements for style.
+
+## Review Checklist
+
+All rules referenced below are defined in `AGENTS.md`. Verify each:
+
+### Architecture
+- [ ] Change is placed in the correct module (see Directory Structure in `AGENTS.md`)
+- [ ] No strands or strands-compose functionality reimplemented (see Key APIs in `AGENTS.md`)
+- [ ] No global state, singletons, or auto-registration introduced
+- [ ] Public API changes are reflected in `src/strands_compose_agentcore/__init__.py`
+
+### Python Rules (see `AGENTS.md` → Python Rules)
+- [ ] `from __future__ import annotations` present in every modified module
+- [ ] All functions/methods fully typed (parameters + return type)
+- [ ] No `Optional`, `Union`, `List`, `Dict` — only `X | None`, `list`, `dict`
+- [ ] Google-style docstring on every new public class, function, and method
+- [ ] Class docstrings on `__init__`, not the class body
+- [ ] No f-strings in `logger.*` calls — `%s` field-value pairs only (see `AGENTS.md` → Logging Style)
+- [ ] No bare `except:` — specific exception types with context messages
+- [ ] Properties returning mutable state return copies: `return list(self._items)`
+- [ ] No hardcoded secrets, no `eval()`, `exec()`, `subprocess(shell=True)`
+
+### Tests
+- [ ] New public code has tests in `tests/` mirroring the source path
+- [ ] Error paths are tested with `pytest.raises`
+- [ ] Tests are named descriptively (see `AGENTS.md` → Testing)
+
+### Commits
+- [ ] Commit messages follow conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`)
+- [ ] No "WIP" commits in the final PR
+
+## Tone
+
+Be direct and specific. Quote the problematic line. Explain why it violates a rule (reference the specific `AGENTS.md` section) and what the fix should be. Don't leave vague comments like "consider refactoring this".

strands_compose_agentcore-0.1.0/.github/agents/tester.agent.md

@@ -0,0 +1,51 @@
+---
+name: tester
+description: Writes and improves tests for strands-compose-agentcore — unit, integration, and example smoke tests
+tools: ["agent", "read", "edit", "search", "execute", "web", "todo"]
+---
+
+You are a testing specialist for strands-compose-agentcore. Your job is to add missing tests, improve coverage, and ensure all test behaviour is correct and well-structured.
+
+**Read `AGENTS.md` first** — it defines the project architecture, Python rules, logging conventions, and testing requirements. Everything below supplements those rules for the testing workflow.
+
+## Environment
+
+This project uses **uv** as the package manager and task runner. Always use `uv run` to execute commands — never bare `python`, `pip`, or `pytest`:
+
+```bash
+uv run just test                   # pytest with coverage (≥90%)
+uv run just check                  # lint + type check + security scan
+uv run pytest tests/test_app.py    # run a specific test file
+uv run pytest -k "test_name"      # run a specific test by name
+```
+
+## Workflow
+
+1. Identify what is under-tested: missing unit tests, edge cases, or error paths.
+2. Place new test files in `tests/` mirroring the `src/strands_compose_agentcore/` path (e.g. `src/strands_compose_agentcore/app.py` → `tests/test_app.py`).
+3. Write tests following all Python rules from `AGENTS.md` (type hints, `from __future__ import annotations`, etc.).
+4. Run `uv run just test` — all tests must pass and coverage must remain ≥ 90%.
+5. Run `uv run just check` — tests must also pass lint and type checks.
+
+## Test Structure Rules
+
+- Test **behaviour**, not implementation details.
+- Name tests descriptively: `test_<what>_<condition>_<expected_outcome>`.
+  - Good: `test_interpolate_missing_var_without_default_raises_value_error`
+  - Bad: `test_interpolate_1`
+- One `assert` concept per test where practical — split into multiple tests rather than one large test.
+- Use `pytest.raises` with `match=` to assert exception messages.
+- Mock at the boundary: patch I/O, network, and strands internals — not internal logic you're testing.
+- Use `tmp_path` for any file system interactions.
+
+## Coverage Targets
+
+- Every public function and method must have at least one test.
+- Error paths (`ValueError`, `KeyError`, `RuntimeError`, etc.) each need a dedicated test.
+- Parametrize repetitive cases instead of copy-pasting test bodies.
+
+## What Not to Change
+
+- Do not modify source code to make tests pass — fix the test or raise an issue.
+- Do not add integration tests for behaviour already covered by unit tests.
+- Do not remove existing tests unless they are genuinely wrong or duplicate.

strands_compose_agentcore-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,46 @@
+# strands-compose-agentcore — Copilot Instructions
+
+**Read `AGENTS.md` in the repository root** — it is the single source of truth
+for all project rules, architecture, Python conventions, logging style, key APIs,
+directory structure, and tooling commands.
+
+This file provides supplementary context for Copilot.
+Do not duplicate rules from `AGENTS.md` here.
+
+## Quick Reference
+
+This is **strands-compose-agentcore**: a deployment adapter that runs
+[strands-compose](https://github.com/strands-compose/sdk-python) YAML configs
+on [AWS Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/).
+
+## Custom Agents
+
+Specialized agents are defined in `.github/agents/`.
+Select the right one for your task:
+
+| Agent | Purpose | Tool Access |
+|-------|---------|-------------|
+| `developer` | Implement features and fix bugs | read, edit, search, execute, agent |
+| `reviewer` | Review PRs for correctness and compliance | read, search, execute (read-only) |
+| `tester` | Write and improve tests | read, edit, search, execute |
+| `docs-writer` | Write and update documentation | read, edit, search, execute |
+
+## Skills
+
+Skills in `.github/skills/` are **automatically activated** when relevant:
+
+| Skill | Triggered When |
+|-------|---------------|
+| `check-and-test` | Validating, linting, testing, or checking code quality |
+| `strands-api-lookup` | Working with strands/strands-compose APIs, checking upstream functionality |
+
+## Path-Specific Instructions
+
+Targeted rules in `.github/instructions/` are applied automatically based on file paths:
+
+| File | Applies To |
+|------|-----------|
+| `source.instructions.md` | `src/**/*.py` |
+| `tests.instructions.md` | `tests/**/*.py` |
+| `examples.instructions.md` | `examples/**/*.py`, `examples/**/*.yaml` |
+| `docs.instructions.md` | `docs/**/*.md` |

strands_compose_agentcore-0.1.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 100
+    commit-message:
+      prefix: ci
+    groups:
+      dev-dependencies:
+        patterns:
+          - "pytest"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 100
+    commit-message:
+      prefix: ci

strands_compose_agentcore-0.1.0/.github/instructions/docs.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: "docs/**/*.md"
+---
+
+# Documentation Instructions
+
+- Use plain English. Short sentences. Active voice.
+- Use bare `python` and `pip` in all command examples — docs target end users who install via pip, not package developers.
+- Every documented feature needs a minimal working YAML example.
+- Python examples must be runnable as-is with `python`.
+- Do not document internal implementation details — only the public API and YAML config surface.
+- Use relative links for files within the repository (never absolute URLs).
+- Keep content consistent with `AGENTS.md` rules and the Key APIs table.

strands_compose_agentcore-0.1.0/.github/instructions/examples.instructions.md

@@ -0,0 +1,14 @@
+---
+applyTo: "examples/**/*.py,examples/**/*.yaml"
+---
+
+# Example Code Instructions
+
+Examples must be complete, easy to understand, and self-contained where runnable.
+
+- Runnable example directories need `config.yaml`, `main.py`, `pyproject.toml`, and `README.md`.
+- Python files must be runnable as-is with `python examples/NN_name/main.py`.
+- YAML files must use valid strands-compose syntax.
+- Use bare `python` and `pip` in all command examples — examples target end users, not package developers.
+- Keep examples minimal — demonstrate one concept per example.
+- Do not import private/internal APIs — only use the public API from `strands_compose_agentcore`.

strands_compose_agentcore-0.1.0/.github/instructions/source.instructions.md

@@ -0,0 +1,16 @@
+---
+applyTo: "src/**/*.py"
+---
+
+# Source Code Instructions
+
+All Python rules from `AGENTS.md` apply. Key reminders for source files:
+
+- `from __future__ import annotations` at the top of every module.
+- Full type annotations on all public functions (parameters + return type).
+- Use `X | None`, `list`, `dict` — never `Optional`, `Union`, `List`, `Dict`.
+- Google-style docstring on every public class, function, and method. Class docstrings go on `__init__`.  Exception: ``@dataclass`` classes use the class body.
+- Structured logging with `%s` and field-value pairs — never f-strings in `logger.*` calls.
+- Use `print()` for user-facing CLI and REPL output. Use `logging.getLogger(__name__)` for diagnostics.
+- Check strands and strands-compose before implementing — do NOT reimplement upstream functionality.
+- Run `uv run just check` and `uv run just test` before committing.

strands_compose_agentcore-0.1.0/.github/instructions/tests.instructions.md

@@ -0,0 +1,19 @@
+---
+applyTo: "tests/**/*.py"
+---
+
+# Test Code Instructions
+
+All Python rules from `AGENTS.md` apply. Additional rules for test files:
+
+- `from __future__ import annotations` at the top of every test module.
+- Name tests descriptively: `test_<what>_<condition>_<expected_outcome>`.
+- Test **behaviour**, not implementation details.
+- One `assert` concept per test where practical.
+- Use `pytest.raises` with `match=` for exception tests.
+- Mock at the boundary: patch I/O, network, and strands internals — not internal logic.
+- Use `tmp_path` for file system interactions.
+- Parametrize repetitive cases instead of copy-pasting test bodies.
+- Run tests with `uv run just test` — never bare `pytest`.
+- In edge cases use `uv run pytest ...` for faster iteration.
+- Coverage must remain ≥ 90%.

strands_compose_agentcore-0.1.0/.github/skills/check-and-test/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: check-and-test
+description: Run lint, type checks, security scan, and tests for strands-compose-agentcore. Use this when asked to validate, check, lint, test, or verify code quality.
+---
+
+# Check and Test
+
+Run the full validation pipeline before committing or opening a PR.
+
+## Steps
+
+1. Run lint, type check, and security scan:
+
+```bash
+uv run just check
+```
+
+2. If `check` fails, auto-format first and re-run:
+
+```bash
+uv run just format
+uv run just check
+```
+
+3. Run the test suite with coverage:
+
+```bash
+uv run just test
+```
+
+4. If a specific test fails, run it in isolation for faster debugging:
+
+```bash
+uv run pytest tests/test_app.py -x -v
+uv run pytest -k "test_name" -x -v
+```
+
+## Coverage
+
+Coverage must remain **≥ 90%**. If coverage drops, add tests for the uncovered code before proceeding.
+
+## Troubleshooting
+
+- **Import errors**: Run `uv run just install` to sync dependencies.
+- **Type errors**: Check for missing `from __future__ import annotations` at the top of the module.
+- **Lint errors**: Run `uv run just format` first — it fixes most style issues automatically.