docs: stop describing the session as one global state.json - #47
Merged
Conversation
0.0.10 moved the session to `~/.artisan/sessions/<hash>/` and the code changed with it. Ten documentation files did not, and kept telling readers that `~/.artisan/state.json` is where the running app is recorded. That is not cosmetic. The field report behind 0.0.12 has an agent concluding it had corrupted a sibling's session, because the tool description it was reading said there was only one slot to corrupt. It reasoned correctly from a document that was wrong. Swept the skill (including law 2, which stated the old model as a rule), the MCP tool descriptions, and the command and MCP doc pages. What remains is what is still true: the legacy pointer exists, is read as a fallback, and is the target of the hand-written recovery recipe. Corrected while there: the "no app detected" recovery said to remove `~/.artisan/state.json`, which clears the pointer and not the session; the troubleshooting table quoted two error strings that no longer exist; and neither carried the `booting: true` path.
anilcancakir
added a commit
that referenced
this pull request
Aug 20, 2026
Ships #47, the documentation sweep. Worth a release rather than a wait: `skills/` is in the pub archive and is what an agent loads, so an unreleased correction means agents keep reading that the session is one global `~/.artisan/state.json` file. That is exactly the misreading that produced the report behind 0.0.12.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why this is not cosmetic
0.0.10 moved the session to
~/.artisan/sessions/<hash>/. The code changed; ten documentation files did not.The field report behind #45 has an agent saying it had corrupted a sibling's
state.jsonwhen the two were never sharing one. It was not confused:artisan_start's own description told it "ONLY ONE Flutter app per machine can be tracked at a time (single-slot state)". The agent reasoned correctly from a document that was wrong. #45 fixed that one description; this is the rest of them.Swept
skills/fluttersdk-artisan/SKILL.mdreferences/mcp-tools.mdreferences/tinker-eval.md,references/state-and-recovery.mddoc/mcp/{overview,setup,tool-reference}.mddoc/getting-started/quickstart.md,doc/commands/{index,start,tinker,mcp-serve}.md25 replacements plus 4 hand-written passages.
What deliberately stays
Every remaining
~/.artisan/state.jsonmention is still true: the legacy pointer exists, is read as a fallback when a project has no session of its own, and is what the documented hand-written recovery targets. I read each in context rather than replacing on sight.Also corrected
rm ~/.artisan/state.json. That clears the pointer, not the session, so the advice did not work. It now names the session directory and says why the pointer is not enough.booting: truepath from fix(state): record the session before the scrape, and recover a lost URI #45, which is now the most likely reason a session looks incomplete.Skill version 0.0.5 -> 0.0.6.
Testing
Docs only, no code touched.
dart formatzero diff,dart analyzezero issues, 1226 tests green.