docs: align CLAUDE.md and make format with the code and CI
Merged
GL
8d ago+23+23+01234567890123456789-21-21-01234567890123456789
What
CLAUDE.md (also AGENTS.md) had drifted from the code, and make format checked less than CI does.
| Where | Was | Now | Evidence |
|---|---|---|---|
| Key Patterns sample | hit["account_id"] | hit["available_accounts"][0]["id"] | No hit has account_id (toolset.py search returns the server's actions plus session_id); README and MIGRATION use available_accounts. The sample raised KeyError. |
top_k | "per connector" | "caps the whole result" | toolset.py return [... for action in hits[:top_k]]; README and MIGRATION say the same |
submit_feedback() account | "the first account" | "the lowest account id in scope" | toolset.py account_ids=[min(scope)]; README and the docstring say lowest id |
| Dev dependency command | uv add --dev pytest | uv add --optional dev pytest | Dev tools live in [project.optional-dependencies].dev; --dev would create a separate [dependency-groups] table |
make format | ty check stackone_ai | ty check stackone_ai examples | CI runs uv run ty check examples as its own step |
How verified
uv run ty check stackone_ai examples: All checks passed.- Cross-checked each corrected statement against the source lines above.
Gates (head 32e0fed)
| Gate | Result |
|---|---|
| Repo skills | none in repo |
| /forge:forge | ran on df47b7f: no change (each claim checked against toolset.py); re-run on 32e0fed: 0 comment lines, 0 copies |
| Security scan | security-reviewer agent: no finding at confidence 70 or above. Aikido: 31 open issues on main (lockfile CVEs, workflow SAST, one old test-fixture secret), none on lines this PR changes |
| Codex security | clean on 32e0fed (job b2f55e81) |
| /security-review | ran: secrets, input validation, transport and DoS items clean; the server-side items do not apply to an SDK |
| /code-review | medium on df47b7f, 6 doc findings, all fixed: Key Patterns runs the hit's own action_id on its own account, the stale per-connector meta tool names are now stackone_search_actions / stackone_execute_action, the Commands and Testing lines say where examples are type-checked, and the format help says it needs make install extras=1 |
| CI | green on 32e0fed: 10 pass, 3 skipped |
| Unresolved review threads | 0 |
Requested by guillaume@stackone.com in Slack (repo audit thread).
š¤ Generated with Claude Code
Summary by cubic
Aligns CLAUDE.md and make format with the actual code and CI behavior.
- Names the global meta tools
stackone_search_actions/stackone_execute_action, one pair across every account in scope, not per-connector. - Fixes the Key Patterns sample, which raised
KeyError: hits carryavailable_accountsandaction_id, and the example now runs the hit's own action on its own account, scopingsubmit_feedback()to that same account. - Corrects
top_kto cap the whole merged result, matchingtoolset.py'shits[:top_k]slice. - Corrects
submit_feedback()to use the lowest account id in scope (min(scope)), not the first account. - Updates the dev dependency command to
uv add --optional dev pytest, since dev tools live in thedevextra. - Adds
examplestomake formattype checks, matching CI so a clean local run won't fail CI.
Documentation and Makefile only; no runtime behavior changes.