Repository navigation
docs: list routine run --json / --quiet, --config and clear-session in the mirror docs (#182) - #191
Conversation
…n the mirror docs (#182) AGENTS.md, GEMINI.md and the write-routine skill now list routine run --json, -s/--quiet and the --config <env> routine run line in their Routine Commands blocks, and AGENTS.md / GEMINI.md carry CLAUDE.md's "Running one command against another environment" subsection. Wording is copied from CLAUDE.md. CLAUDE.md's Sessions section and the setup-api troubleshooting list now say to run config clear-session after editing credentials in config.json by hand, since hand edits bypass the clear-on-save.
garretpremo
left a comment
There was a problem hiding this comment.
🤖 Automated review by claude — generated by the
review-issueskill. Treat as advisory; a human still owns the merge decision.
The doc diff itself is correct. In AGENTS.md and GEMINI.md, the Routine Commands lines, the Built-in Commands table and the "Running one command against another environment" subsection match origin/dev:CLAUDE.md (8b5e090) byte for byte. write-routine and setup-api match the shipped routine run / config clear-session / leading --config code, and the new CLAUDE.md Sessions bullet matches SessionManager.load(): url and user are part of the binding check, password isn't. One thing blocks: the "Post-release wiki edits" section can't be applied as written. Applying it would stop git from ignoring the legacy session file.
Blocking:
-
Recommended-Gitignore.md: the replacement line has a trailing comment, and gitignore doesn't support those.#only starts a comment at the beginning of a line. So.apijack/session.json # written by releases before per-environment sessions; drop once the file is deletedbecomes one literal pattern, and it no longer matches.apijack/session.json. I checked this in a scratch repo with exactly those two lines.git check-ignore -v .apijack/session.jsonmatched nothing, andgit statuslisted?? .apijack/session.json. A project that follows the edit would start committing the legacy file, which the body itself says "may still hold valid tokens". Both the "Recommended patterns" block and the "Minimal gitignore" block ("same replacement") have this problem. Put the comment on its own line:.apijack/sessions/ # Written by releases before per-environment sessions; drop once the file is deleted .apijack/session.json
This only needs a PR-body edit. No commit is required.
Non-blocking observations
Authentication-Configuration.md→ "Priority" (around line 77) is stale after #180, and the wiki list doesn't touch it. It still readsEnvironment variables → config file active environment → null. A leading--config <name>(andcreateCli({ environment })) now comes before the env vars (resolveEnvironmentinsrc/config.tsskips them whenopts.environmentis set). Consider adding--config <name> →at the front, with a link to the newCLI-Command-Referencesection.CLI-Command-Reference.md→## routine runintro. "progress is printed to stdout" is no longer true with--jsonor-s. A small rewording, such as "(unless--jsonor--quiet)", would keep it consistent with the new flag rows.Authentication-Configuration.md→ "Session File Location" table. Sessions now sit next toconfig.json, so a third row for a customconfigPath(<dir of configPath>/sessions/<env>.json) would be accurate.CLAUDE.mdalready documents this case.- I verified the rest of the wiki list against the current wiki (
a20bc7c) and the code ondev, and it applies as written:- Every target heading, table and sentence exists.
- The
#global-option---config-nameanchor matches the new heading. - The
config clear-sessiondefault order (--config→<CLI>_URL/_USER/_PASS→ active) matchesresolveEnvironment. - Unknown-name and name-with-
--allexit 1, matchingconfigClearSessionAction. - The on-disk
{ env, baseUrl, username, session }shape matchesSessionFile. - Every
session.jsonreference in the wiki is covered.
Nitpicks
- The new
AGENTS.md/GEMINI.mdsubsection keepsCLAUDE.md's domain-specific example (admin matters delete 7,routine run cleanup --set matterId=2). That follows the "copy verbatim" triage decision, so it's fine here. The genericpets/resourcesexamples used elsewhere (and in this PR's wiki text) might suit a futureCLAUDE.mdpass better.
garretpremo
left a comment
There was a problem hiding this comment.
🤖 Automated review by claude — generated by the
review-issueskill. Treat as advisory; a human still owns the merge decision.
Follow-up on the updated PR body. The head is still fc1a50c; there are no new commits. The blocker is fixed, nothing new blocks, and this is ready for a first pass.
- Blocker fixed. In both gitignore blocks, the
Recommended-Gitignore.mdcomment now sits on its own line. I tested the "Recommended patterns" block in a scratch repo.git check-ignore -vmatches.apijack/session.json(line 5),.apijack/sessions/dev.json(line 3) and.apijack/config.json, andgit statusshows only.gitignoreas untracked. - Non-blocking items addressed. I checked each one against the current wiki (
a20bc7c) anddev:## routine runintro. The intro sentence being replaced exists word for word.- "Environment Variable Naming" sentence. The sentence being replaced exists word for word, and the
CLI-Command-Reference#global-option---config-namelink matches the new heading. - "Priority" block. The new order matches
resolveEnvironment(): a selected environment skips the env vars, and a leading--configoverridescreateCli({ environment }). - Custom
configPathrow. It matchesconfigDir = resolve(configPath, '..')incli-builder.ts.
garretpremo
left a comment
There was a problem hiding this comment.
🤖 Final review by claude — generated by the
final-reviewskill. CI is green, no blockers, soak window elapsed. Marking approved and merging.
Approved.
Closes #182
Summary
The shipped mirror docs (
AGENTS.md,GEMINI.md, and thewrite-routineandsetup-apiskills) now cover every new flag in this release:routine run --jsonand-s/--quiet(#177),config clear-session(#179), and the global--config <name>(#180). The wording is copied fromCLAUDE.md. Per #182's triage, this is the last PR of the release, so the mirrors are updated in a single pass againstCLAUDE.md's final text (dev8b5e090, after #190).The wiki goes live on push, so the wiki edits aren't in this PR. They're listed below under "Post-release wiki edits", to be applied as written once the release ships.
What changes
Routine Commands blocks:
AGENTS.md,GEMINI.md,skills/write-routine/SKILL.mdThree lines are added, matching
CLAUDE.md:write-routinekeeps its own column alignment.Global
--config <name>:AGENTS.md,GEMINI.mdCLAUDE.md's "Running one command against another environment" subsection is copied verbatim after the Built-in Commands table, which is whereCLAUDE.mdputs it.--configrow in the Built-in Commands tables and the setup-api Multi-Environment line came with feat: global --config <name> runs one command against any configured environment (#180) #190 itself.config clear-sessioncame with feat: keep one session per environment instead of a shared session.json (#179) #186.CLAUDE.md"Sessions"config.jsonby hand bypasses the clear-on-save. A changedurloruseris still caught, but a changedpasswordisn't, so runconfig clear-sessionafterwards. feat: keep one session per environment instead of a shared session.json (#179) #186's review flagged this.skills/setup-api/SKILL.mdTroubleshootingconfig.jsonby hand → runapijack config clear-session, orapijack config clear-session <env>for another environment.Not changed
The broader
AGENTS.md/GEMINI.mdresync is out of scope per the triage: built-in resolvers, programmaticrunRoutine, the plugin system,SessionAuthStrategyoptions, project extensions, aliases and opt-in auth.Acceptance criteria
The Routine Commands block in
AGENTS.md,GEMINI.mdandskills/write-routine/SKILL.mdlistsroutine run <name> --jsonandroutine run <name> -s / --quiet, worded as inCLAUDE.md.config clear-session [name] [--all]appears in the Built-in Commands table ofAGENTS.mdandGEMINI.md, and in setup-api's Multi-Environment block. These came with feat: keep one session per environment instead of a shared session.json (#179) #186; checked here.The global
--config <name>is documented:AGENTS.md/GEMINI.md, whereverCLAUDE.mdputs it: the table row from feat: global --config <name> runs one command against any configured environment (#180) #190 ("goes before the command"), the Routine Commands line, and the subsection, which states the before-the-command rule;--config <env> routine run <name>line in write-routine's Routine Commands block;write-routine and setup-api show the before-the-command placement by example.
CLAUDE.md"Sessions" says to runconfig clear-sessionafter editing credentials inconfig.jsonby hand.Nothing else in the mirrors changes.
This body has a "Post-release wiki edits" section that can be applied as written.
Test plan
bun test: 1324 pass / 0 fail (docs only, run once)bun run lint: 0 errorsCLAUDE.mdon dev8b5e090: identical.CLAUDE.mdand the wiki edits against the current wiki and the shipped code. Verdict: the staged diff was clean. Its eight findings are all fixed:Invalidating the Sessionline, the env-var case in theconfig clear-sessiontext, exact text for the--configsection, and keeping the legacy gitignore line.CLAUDE.mdbullet, and<env>in the setup-api bullet.changes requested, PR-body only):#comment, which gitignore treats as part of the pattern. It now sits on its own line.routine runintro, and a custom-configPathrow in the session-location table.Project-Mode.md,Managing-Environments.md) only use.apijack/with no trailing comments, so they're unaffected.Post-release wiki edits
Apply these to
normalled/apijack.wikionce the release containing #177, #179, #180 and #182 has shipped.CLI-Command-Reference.md## routine run, intro. "Steps are run in order; progress is printed to stdout." → "Steps are run in order; progress is printed to stdout (unless--jsonor-s/--quietis passed)."Flags table. Add two rows after
--dry-run:Below the table, add:
Add to the Examples block:
## config switch. After "All subsequent commands use the URL and credentials of the named environment.", add:New section
## config clear-session, after## config switch:New section before
## Global Flags (Generated API Commands):Writing-Routines.md"Running and validating routines" table. Add three rows after
routine run <name> --dry-run:Recommended-Gitignore.mdSessions moved from
.apijack/session.jsonto.apijack/sessions/<env>.json(#179). Keep ignoring the old file until it's deleted, because it may still hold valid tokens."Recommended patterns" block: replace the
.apijack/session.jsonline with the three lines below. gitignore only treats#as a comment at the start of a line, so the comment has to sit on its own line:"Minimal gitignore" block: same replacement.
"What to commit" table: replace the
.apijack/session.jsonrow with these two rows:Authentication-Configuration.md("Environment Variable Naming" and "Session Caching")"Environment Variable Naming", first sentence. "Environment variables take priority over the config file." → "Environment variables take priority over the config file's active environment, but not over a leading
--config <name>(see CLI Command Reference).""Priority" block (Global --config <name> option to run a command against any configured environment #180):
"Session File Location" table:
~/.<cliName>/session.json→~/.<cliName>/sessions/<env>.json, and.apijack/session.json→.apijack/sessions/<env>.json. Add a third row:Add below the table:
"
AuthSessionFormat". Add after the field table:"Session Lifecycle", step 1: "Load
session.jsonfrom disk." → "Load the environment's session file from disk (ignored if it was recorded for a differentbaseUrlor username).""Invalidating the Session": "This deletes
session.json." → "This deletes the environment's session file (sessions/<env>.json). From the CLI,config clear-session [name] [--all]does the same."Managing-Environments.md("Switching environments")After the existing paragraph, add: