docs: align CLAUDE.md and make format with the code and CI

Merged
GL
8d ago
+23-21

What

CLAUDE.md (also AGENTS.md) had drifted from the code, and make format checked less than CI does.

WhereWasNowEvidence
Key Patterns samplehit["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 commanduv add --dev pytestuv add --optional dev pytestDev tools live in [project.optional-dependencies].dev; --dev would create a separate [dependency-groups] table
make formatty check stackone_aity check stackone_ai examplesCI 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)

GateResult
Repo skillsnone in repo
/forge:forgeran on df47b7f: no change (each claim checked against toolset.py); re-run on 32e0fed: 0 comment lines, 0 copies
Security scansecurity-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 securityclean on 32e0fed (job b2f55e81)
/security-reviewran: secrets, input validation, transport and DoS items clean; the server-side items do not apply to an SDK
/code-reviewmedium 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
CIgreen on 32e0fed: 10 pass, 3 skipped
Unresolved review threads0

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 carry available_accounts and action_id, and the example now runs the hit's own action on its own account, scoping submit_feedback() to that same account.
  • Corrects top_k to cap the whole merged result, matching toolset.py's hits[: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 the dev extra.
  • Adds examples to make format type checks, matching CI so a clean local run won't fail CI.

Documentation and Makefile only; no runtime behavior changes.