Repository navigation
feat: onboarding Phase 1: .sctx.json discovery, setup-space, session preflight - #175
Merged
Merged
Conversation
…r clash The config is now found from --config, then $SCTX_CONFIG, then the nearest .sctx.json walking up from the working directory, then the global file. A local config is no longer shadowed by a global one, and ./config.json in the working directory is no longer read (set SCTX_CONFIG or rename it to .sctx.json). includeSpacesFrom: a space in the including file overrides an included space of the same name instead of throwing, later includes override earlier ones, a missing include reports E_INCLUDE_NOT_FOUND, and a leading ~ is expanded. Config load errors carry stable codes (SctxError) so hooks and skills can map them to a fix.
sctx spaces now checks that the config loads and that each space's path and schema exist, reporting problems as stable codes with a fix. --json returns the config path and how it was found, plus the problems, and exits 1 on an error. A missing config is reported at info level, not as a failure. sctx spaces add <name> <path> --schema <s> writes to the config found by walking up, or the one named by --config. When discovery would land on the global file or on nothing, it requires --config or --global. It will not rewrite a config that uses JSON5 features; it prints the entry to add instead.
A SessionStart hook runs 'sctx spaces --json' for the session's directory and, on failure, shows one message with a stable code (E_SCTX_UNAVAILABLE, E_SCTX_OUTDATED, E_CONFIG_INVALID, E_SPACE_PATH_MISSING, ...) and gives the agent the fix. With a healthy config it tells the agent which spaces apply; with none it points at the setup-space skill. A missing Bun is reported by the shell guard in hooks.json, which also keeps the other hooks silent. The other hooks treat an unusable 'sctx' answer as 'no spaces' and say nothing, and pick the config up again as soon as it is fixed. An unexpected error in a hook becomes one E_HOOK_FAILED message per session with exit 0 instead of a bare exit 1. Only new validation errors in the Stop hook still block. The CLI is run from the session's directory, preferring an installed sctx and otherwise bunx pinned to the plugin's version.
The plugin's patch number moves independently of the package's, so it does not name a published structured-context release.
… code setup-space takes a user from no config to one working space and one validated edit: check the setup, get familiar with the content by sampling, propose a single space, write it with 'sctx spaces add', summarise the validation gap, make a guided first edit, and mention the Obsidian plugin after a first-time setup in a vault. It hands off to the structured-context skill for schema design. The structured-context skill gains references/troubleshooting.md, one row per error code with the diagnosis and fix, and its config section now describes .sctx.json discovery.
Library callers that already know where the config belongs, such as the Obsidian plugin writing to the vault's .sctx.json, can name it instead of relying on discovery.
A schema written as an sctx:// URI or without its .json extension was accepted and only failed later in validate. Every non-URL schema must now resolve to a file before the space is written.
…n no schema fits Found by running the skill against three real vaults: agents tried 'spaces add' without a target first, wrote the schema without its extension, and one wrote a custom schema mid-setup instead of stopping.
The SessionStart check no longer says anything when no config exists, and no longer suggests setup-space when a config has no spaces. It still reports failures once and lists the spaces that apply when it is healthy.
mindsocket
commented
Oct 27, 2026
mindsocket
left a comment
Owner
Author
There was a problem hiding this comment.
Overcooked and sloppy in places. Lots of docs tightening needed.
Put lessons from these comments into AGENTS.md standards and for docs, a new doc-review kill to avoid this in future (applies to all written content - README, skills, references, docs.
Move config code into src/config/, trim the public API to what the Obsidian plugin uses, and make the write-target error independent of the CLI. Tighten the setup-space skill, troubleshooting reference, README and config docs, and fold the setup-space command into its skill.
Owner
Author
|
Addressed all 37 review comments, with a reply on each thread.
Core tests (845 pass, 15 skipped), hook tests, typecheck and lint pass. The Obsidian branch is updated to match and is still local. |
mindsocket
commented
Oct 27, 2026
| const resolved = resolveConfigPath(options.startDir); | ||
| if (options.global) { | ||
| if (resolved.source === 'override' || resolved.source === 'env') { | ||
| throw new SctxError('E_TARGET_REQUIRED', '--global cannot be combined with --config or $SCTX_CONFIG'); |
Owner
Author
There was a problem hiding this comment.
Much better, but "Name the config" is awkward. How about "Specify the config file location or global option" instead?
… tests, reword target error
mindsocket
marked this pull request as ready for review
October 27, 2026 03:25
Code reviewNo issues found. Checked for bugs and CLAUDE.md compliance. |
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
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.
Refs #145. Phase 1 of the onboarding journey: from "installed the Claude Code plugin" to a configured space and a first agent edit that stays valid, for someone with an existing folder or Obsidian vault.
What changes
Config discovery (breaking)
--config, then$SCTX_CONFIG, then the nearest.sctx.jsonwalking up from the working directory, then the global file. Nearest wins and nothing is merged by location../config.jsonlookup is removed. Rename it to.sctx.jsonor setSCTX_CONFIG."path": "."is the whole vault.includeSpacesFrom: a space in the including file overrides an included space of the same name instead of throwing; later includes override earlier ones; a leading~is expanded; a missing include reportsE_INCLUDE_NOT_FOUND.sctx spacesE_CONFIG_NOT_FOUND,E_SPACE_PATH_MISSING,E_SCHEMA_NOT_FOUND, ...), each with a fix.--jsonincludes them. Exits 1 on an error; a missing config with nothing set is info and exits 0.sctx spaces add <name> <path> --schema <file>writes to the config found by walking up, or the one named by--config. When discovery would land on the global file or on nothing it requires--config <folder>/.sctx.jsonor--global. It will not rewrite a file with comments or trailing commas (prints the entry instead), and rejects a schema that does not resolve.addSpaceandcheckConfigare exported fromstructured-context/apifor other hosts.Claude Code plugin
SessionStarthook runssctx spaces --jsonfor the session folder. It reports a broken setup once, with a code, and tells the agent which spaces apply when healthy. It says nothing when no config exists.E_HOOK_FAILEDmessage per session with exit 0 instead of a bare exit 1. Only new validation errors in the Stop hook still block.E_NO_BUN) and keeps the other hooks quiet.sctxif there is one, otherwisebunxpinned to the plugin's major.minor.setup-spaceskill and/setup-spacecommand: look at the content by sampling, propose one space, write it withsctx spaces add, summarise the validation gap, make a guided first edit. Thestructured-contextskill gainsreferences/troubleshooting.md, one row per error code.Verification
bun test: 909 pass, 0 fail; typecheck and lint clean.claude -pwith this plugin against copies of three real vaults. A strategy-tree vault and a mixed inbox were set up and edited validly; the hooks ran silently. A 279-note playbook vault had no fitting bundled schema, the agent wrote its own and hit the turn cap; the skill now stops and explains instead.bunx structured-context@0.14.0 --versionwith an empty cache took 2.2s and a warm one 0.16s, against the 30s prompt-hook cap (one run, one network).Not in this PR
Review notes
plugin installdoes not fireSessionStart; whether/setup-spaceloads without a restart is unchecked.