Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
5fa4a91
feat(config): find .sctx.json by walking up; included spaces no longe…
mindsocket Oct 26, 2026
b29ef1e
feat(spaces): report config problems with codes; add 'spaces add'
mindsocket Oct 26, 2026
88cb615
docs(config): document .sctx.json discovery, includes and 'spaces add'
mindsocket Oct 26, 2026
20a72b4
feat(plugin): SessionStart preflight; hooks fail quietly and recover
mindsocket Oct 26, 2026
e10db51
fix(plugin): pin bunx to the plugin's major.minor, not its patch version
mindsocket Oct 26, 2026
6cb03f7
fix(spaces): store '.' for the config folder when reached through a s…
mindsocket Oct 26, 2026
9654749
feat(plugin): setup-space skill and command; troubleshooting by error…
mindsocket Oct 26, 2026
181a0e2
feat(spaces): addSpace accepts an explicit configFile
mindsocket Oct 26, 2026
bed2270
fix(spaces): 'spaces add' rejects a schema that does not resolve
mindsocket Oct 26, 2026
4b9feda
docs(plugin): setup-space names the target on first run and stops whe…
mindsocket Oct 26, 2026
ab6f5a7
docs: describe .sctx.json discovery in the contributor notes
mindsocket Oct 26, 2026
7b95fbe
docs: mention setup-space and .sctx.json; drop the session nudge
mindsocket Oct 26, 2026
fc8650b
refactor(config): address PR review on onboarding
mindsocket Oct 27, 2026
d261a8b
docs: write down review lessons in AGENTS.md and add a doc-review skill
mindsocket Oct 27, 2026
02cc72f
docs(plugin): setup-space notes untyped files are ignored, not failed
mindsocket Oct 27, 2026
3af6b6f
refactor(config): keep add-space types internal, mirror src/config in…
mindsocket Oct 27, 2026
9addc84
Merge branch 'main' into feat/onboarding-phase1
mindsocket Oct 27, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions .claude/skills/doc-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
---
name: doc-review
description: Review written content in this repo (README, docs/, AGENTS.md, plugin skills and references, CLI help and error text) against the project's documentation standards, then fix what it finds. Use after writing or changing any prose, before committing or opening a PR.
---

## Task

Review the prose in the target named by `$ARGUMENTS`: a PR number, branch, commit, or list of files. With no
argument, use uncommitted changes, or if there are none, the branch against `main` (`git diff main...HEAD`).
Look at `*.md`, `plugin/**`, and user-facing strings in `src/` and tests. Apply the **Documentation Principles** in
`AGENTS.md`, then fix the findings. Re-read each finding in context: a flagged phrase is sometimes the right
wording.

## Checks

For every changed passage, ask:

1. **Would someone new to the project understand it?** Flag decision history and internal jargon ("never merged by
location", "A′", phase names). Say what does happen.
2. **Does it earn its place?** Flag sentences that restate the previous one, state the obvious, spell out an
implication the reader can work out, or describe what is not the case without a likely wrong assumption to
correct. Flag error codes and flags the output already shows.
3. **Is it in the right place?** Flag duplicated explanations (owned once, linked elsewhere). A README section is
a sentence or two pointing to docs/. Detail used rarely belongs in `references/` or `sctx docs`.
4. **Is a recommendation labelled as one?** "It is recommended to..." rather than a rule stated as fact.
5. **Names:** `structured-context` in prose, `sctx` only in commands. Terms match `docs/concepts.md`.

Skills and references (`plugin/skills/**`), also:

6. **Trigger:** the `description` names structured-context (sctx) and the task in words a user or agent would
use, briefly. It does not rely on terms an agent session may not know (such as "space").
7. **Every line is an action or a fact the agent lacks.** Flag instructions made redundant by the next command,
output that already says the same thing, steps that depend on a state check ("if there is no config yet")
when intent alone should trigger the skill, and rules that limit what a capable model would do unprompted.
8. **Offers and confirmations** only where the user's decision changes what happens next.
9. **Order follows the user's journey**, happy path first.

Code comments and messages:

10. Flag comments that restate code or explain history, and library errors that mention CLI flags.

## Output

List findings as `file:line, check number, proposed rewrite`, then apply them. Run `bun run lint` and, if
`plugin/` changed, `bun run test:hook`. Finish by checking the "Definition of done" table in `AGENTS.md` for files
the change affects but does not touch.
6 changes: 5 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Before starting new work, review [docs/concepts.md](docs/concepts.md) for canoni
- see `package.json`
- Releases go through the `/release` skill.

Space names (e.g. `personal`, `politics`) are resolved via a config file - `$SCTX_CONFIG`, `$XDG_CONFIG_HOME/structured-context/config.json`, `--config <file>` param, or `./config.json`
Space names (e.g. `personal`, `politics`) are resolved via a config file - `$SCTX_CONFIG`, `$XDG_CONFIG_HOME/structured-context/config.json`, `--config <file>` param, or the nearest `.sctx.json` walking up from the working directory

The lefthook pre-commit hook syncs the plugin version (below), then runs biome (`--write`, re-staged) and the typecheck.

Expand Down Expand Up @@ -54,6 +54,7 @@ There are several places that need reviewing and updating with any new feature o
- **Minimise blast radius:** Protect established boundaries and interfaces. Treat unnecessary ripple effects (such as making synchronous APIs asynchronous or adding dual APIs) as a design smell indicating the approach should be re-evaluated.
- **Public API surface:** Do not add exports to `src/api.ts`, `src/types.ts` or `src/testing.ts` (the `structured-context/api`, `/types` and `/testing` entry points), or add types or hooks to the plugin interface, without the maintainer's explicit agreement on that specific surface. Exporting something to make docs complete, to tidy up, or because a feature has a public-looking class is not a reason. If a change seems to need a new export, stop and propose it, with the consumer that needs it. Internal modules can change freely.
- **Where a setting lives:** Config says *what* to use, CLI flags override it for one run, and the environment holds secrets and the config location only (`apiKeyEnv` names a secret; `SCTX_CONFIG` locates the config). Do not add env vars that set config values, and never infer a choice (such as a judge provider) from a variable that happens to be set: a key present for another tool must not be spent silently. Config also never switches on costly or outward-facing behaviour (such as semantic judging): each run asks for it, through a flag or an API option.
- **Reuse types:** Derive a type from the real one (`Pick`, `Partial`) instead of restating its shape. Keep CLI wording (flags, commands) out of library errors and the public API; the CLI adds its own hint. Once a feature has many files, give it a directory. Comments explain why, never restate the code.
- **Failures are visible:** A rule or expression that cannot be evaluated is reported as a violation, never skipped or treated as a pass. Likewise a misconfiguration fails before any work or spend.

## Documentation Principles
Expand All @@ -62,6 +63,9 @@ There are several places that need reviewing and updating with any new feature o
- **Document what it does, not what it doesn't:** Describe behaviour and purpose. State a limit only when a new user would realistically assume otherwise. Specification and decision history do not leak into docs.
- **Proper name in docs:** `structured-context` is the project name for prose; `sctx` is only the CLI command in command examples.
- **Approachability:** Write short, declarative sentences in active voice, one idea per sentence — about 80% of the way to ASD-STE100. Introduce a concept once, before sections that need it. Frame options by purpose (what each is for, and for whom).
- **Plain language:** Say what happens. Leave out decision history and internal jargon ("never merged by location"), error codes the output already shows, restatements of the sentence before, and "implications" the reader can work out. Label a recommendation as a recommendation.
- **README stays short:** A README section is a sentence or two that points to docs/. Setup mechanics, failure behaviour and edge cases go in docs/.
- **Skills and references:** Every line is an action or a fact the agent lacks. Cut instructions the next command makes redundant, and do not state what command output already says. Do not over-constrain capable models with rules for situations they handle. The `description` uses the words a user or agent would use, naming structured-context (sctx) and the task in plain terms. `SKILL.md` holds the common path; detail goes in `references/` or `sctx docs`. Prefer a skill to a slash command, since the two are interchangeable.
- **Front-load the happy path:** Quick starts give the fewest steps that run. Tuning, alternatives and edge cases come after.

## Key Files
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,8 @@ claude plugin marketplace add mindsocket/structured-context
claude plugin install structured-context
```

Ask Claude to set up a space (or run `/setup-space`) in the folder that holds your notes. The plugin's hooks need Bun.

Skills can also be installed standalone without the plugin:

```
Expand All @@ -89,7 +91,7 @@ See [docs/concepts.md](docs/concepts.md) (`sctx docs concepts`) for terminology:

## Configuration

The config file maps space names to paths and schemas, with optional plugin settings. It is found from `--config`, then `$SCTX_CONFIG`, then `$XDG_CONFIG_HOME/structured-context/config.json` (default `~/.config/...`), then `./config.json`. Paths resolve relative to the config file, and `includeSpacesFrom` pulls in spaces from other config files.
The config file maps space names to paths and schemas, with optional plugin settings. It is found from `--config`, then `$SCTX_CONFIG`, then the nearest `.sctx.json` walking up from the working directory, then `$XDG_CONFIG_HOME/structured-context/config.json` (default `~/.config/...`). Paths resolve relative to the config file, and `includeSpacesFrom` pulls in spaces from other config files.

See `config.example.json` and [docs/config.md](docs/config.md) (`sctx docs config`) for the full reference, including `fieldMap`, `typeInference`, templates, filter views and plugin loading.

Expand Down
2 changes: 1 addition & 1 deletion docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The following diagram shows the high-level flow from configuration and source fi

```mermaid
flowchart LR
config([config.json<br>space definition])
config([.sctx.json or config.json<br>space definition])
schema[(Schema<br>json-schema/JSON5)]
space[(Space<br>directory or file)]

Expand Down
2 changes: 1 addition & 1 deletion docs/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This document is the canonical reference for concepts and terminology used in th

## Space

A **space** is a named collection of nodes organised according to a schema. Spaces are the primary unit of organisation — a space has a backing format (a `space directory` or a `space on a page` file) and may be registered in `config.json` with a name for convenient access.
A **space** is a named collection of nodes organised according to a schema. Spaces are the primary unit of organisation — a space has a backing format (a `space directory` or a `space on a page` file) and may be registered in a config file (`.sctx.json` or the global `config.json`) with a name for convenient access.

```mermaid
flowchart TD
Expand Down
29 changes: 23 additions & 6 deletions docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,30 @@ title: "Configuration Reference"

## Config file location

structured-context looks for its config file in this order:
structured-context uses the first config file it finds, in this order:

1. `$SCTX_CONFIG` — explicit path override
2. `~/.config/structured-context/config.json` (or `$XDG_CONFIG_HOME/structured-context/config.json`)
3. `./config.json` in the current working directory
1. `--config <path>`
2. `$SCTX_CONFIG`
3. The nearest `.sctx.json`, looking in the working directory and then each parent folder
4. `~/.config/structured-context/config.json` (or `$XDG_CONFIG_HOME/structured-context/config.json`)

See `config.example.json` for the full structure. Paths in config files are resolved relative to the config file.
It is recommended to keep a `.sctx.json` at the base of the notes it describes (for example the root of an Obsidian vault), or to use the global config. The CLI and agent sessions look in parent folders only, so run commands from inside the folder that holds the config. To use the spaces from another config file too, list it in `includeSpacesFrom`.

Paths in a config file are relative to the folder that holds that file. In a `.sctx.json` at a vault root, `"path": "."` is the whole vault and `"path": "notes"` is one folder.

`sctx spaces` shows which config file is used and reports problems with it. `sctx spaces --json` returns the same information for tools and hooks.

### Adding a space

```bash
sctx spaces add wiki notes --schema knowledge_wiki.json
```

This adds the space to the config file found from the working directory, or to the one named with `--config`. When no `.sctx.json` is found, or only the global config exists, pass `--config <folder>/.sctx.json` (creates the file) or `--global`. If the config file has comments or trailing commas, the command prints the entry to add by hand.

Custom schemas can sit anywhere. Reference them by relative path, for example `./.sctx/schemas/my_wiki.json`; `.sctx/schemas/` is the suggested folder.

See `config.example.json` for the full structure.

## Spaces

Expand All @@ -36,7 +53,7 @@ A space is a named directory or single file registered in the config. Example:
- A plugin schema prefixed with the plugin name (e.g. `sctx-wardley-mapping/wardley_map.json` or `wardley-mapping/wardley_map.json`). Specifying a plugin-prefixed schema automatically loads that plugin for the space.
- A simple filename (e.g. `wardley_map.json`) provided by a plugin explicitly declared under `plugins`.

**`includeSpacesFrom`** — import space definitions from other config files. Useful for aggregating spaces from multiple projects into a central config. Duplicate space names are not allowed.
**`includeSpacesFrom`** — import space definitions from other config files, for example a shared team config or your global config (`"~/.config/structured-context/config.json"`; a leading `~` is expanded). A space defined in the including file overrides an included space of the same name; between includes, later entries win. Only `spaces` are taken from an included file.

A config must define at least one of `spaces` or `includeSpacesFrom`. When using `includeSpacesFrom` alone, `spaces` can be omitted entirely.

Expand Down
1 change: 1 addition & 0 deletions docs/use-cases.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ A catalog of use cases for structured-context, covering both direct CLI usage an

| Use case | Description | Status | Coverage |
|---|---|---|---|
| **Set up a space** | Find structured content in a folder, choose a schema, write the config and make a first validated edit | agent | `/setup-space` skill · `sctx spaces add` · `sctx spaces` reports config problems with codes |
| **Author new content compliantly** | Create or edit nodes in Obsidian while staying schema-conformant | partial | Plugin hooks report issues introduced during a Claude turn; schema-driven templates; structured-context skill for inline guidance |
| **Discover and curate inputs** | Identify new information (research, signals, events) to add to a space and integrate it | none | — |

Expand Down
161 changes: 161 additions & 0 deletions hook-test/unit/preflight.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
/**
* Unit tests for plugin/scripts/preflight.ts and safe.ts
*
* Tests call runPreflight() directly, with the real CLI as a subprocess.
*/

import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { runOnPrompt } from '../../plugin/scripts/on-prompt';
import { runPreflight } from '../../plugin/scripts/preflight';
import { runSafely } from '../../plugin/scripts/safe';
import { loadState, sctxCommand, stateFilePath } from '../../plugin/scripts/state';
import { type IsolatedFixtures, isolateFixtures } from '../fixture-utils';

const SCTX_BIN = join(import.meta.dir, '../../src/index.ts');

let fixtures: IsolatedFixtures;
let stateDir: string;
let sessionId: string;

beforeEach(() => {
fixtures = isolateFixtures();
stateDir = join(tmpdir(), `ost-preflight-state-${crypto.randomUUID()}`);
sessionId = crypto.randomUUID();
});

afterEach(() => {
fixtures.cleanup();
rmSync(stateDir, { recursive: true, force: true });
});

const opts = () => ({ stateDir, sctxBin: SCTX_BIN, configPath: fixtures.configPath });

describe('runPreflight', () => {
it('tells the agent which spaces apply when the config is healthy', async () => {
const result = await runPreflight({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());

expect(result.systemMessage).toBeUndefined();
expect(result.additionalContext).toContain('test-space');
});

it('says nothing when no space relates to the directory', async () => {
const unrelated = join(tmpdir(), `ost-preflight-unrelated-${crypto.randomUUID()}`);

const result = await runPreflight({ session_id: sessionId, cwd: unrelated }, opts());

expect(result).toEqual({});
});

it('says nothing when there is no config', async () => {
const dir = join(fixtures.fixtureDir, 'empty');
mkdirSync(dir, { recursive: true });
const noConfig = { stateDir, sctxBin: SCTX_BIN, configPath: undefined };
const saved = { SCTX_CONFIG: process.env.SCTX_CONFIG, XDG: process.env.XDG_CONFIG_HOME };
delete process.env.SCTX_CONFIG;
process.env.XDG_CONFIG_HOME = join(fixtures.fixtureDir, 'xdg');
try {
const result = await runPreflight({ session_id: sessionId, cwd: dir }, noConfig);

expect(result).toEqual({});
} finally {
if (saved.SCTX_CONFIG !== undefined) process.env.SCTX_CONFIG = saved.SCTX_CONFIG;
if (saved.XDG !== undefined) process.env.XDG_CONFIG_HOME = saved.XDG;
else delete process.env.XDG_CONFIG_HOME;
}
});

it('reports a moved space path with its code and a fix', async () => {
rmSync(fixtures.vaultDir, { recursive: true, force: true });

const result = await runPreflight({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());

expect(result.systemMessage).toContain('E_SPACE_PATH_MISSING');
expect(result.additionalContext).toContain('Fix:');
expect(result.additionalContext).toContain('Troubleshooting');
});

it('reports an unreadable config', async () => {
writeFileSync(fixtures.configPath, '{ not json');

const result = await runPreflight({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());

expect(result.systemMessage).toContain('E_CONFIG_INVALID');
});

it('reports a CLI that cannot run', async () => {
const result = await runPreflight(
{ session_id: sessionId, cwd: fixtures.fixtureDir },
{ ...opts(), sctxBin: join(fixtures.fixtureDir, 'does-not-exist.ts') },
);

expect(result.systemMessage).toContain('E_SCTX_UNAVAILABLE');
});

it('reports a CLI older than the plugin expects', async () => {
const old = join(fixtures.fixtureDir, 'old-sctx.ts');
writeFileSync(old, 'console.log(JSON.stringify({ configFiles: [], spaces: [] }));');

const result = await runPreflight({ session_id: sessionId, cwd: fixtures.fixtureDir }, { ...opts(), sctxBin: old });

expect(result.systemMessage).toContain('E_SCTX_OUTDATED');
});
});

describe('other hooks stay quiet when setup is broken', () => {
it('on-prompt writes no state and does not throw for a broken config', async () => {
writeFileSync(fixtures.configPath, '{ not json');

await runOnPrompt({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());

expect(loadState(stateFilePath(sessionId, opts())).baseline).toEqual({});
});

it('on-prompt recovers once the config is fixed, without a new session', async () => {
const good = await Bun.file(fixtures.configPath).text();
writeFileSync(fixtures.configPath, '{ not json');
await runOnPrompt({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());

writeFileSync(fixtures.configPath, good);
await runOnPrompt({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());

expect(Object.keys(loadState(stateFilePath(sessionId, opts())).baseline)).toEqual(['test-space']);
});
});

describe('runSafely', () => {
it('turns an error into one message per session and does not rethrow', async () => {
const saved = process.env.SCTX_STATE_DIR;
process.env.SCTX_STATE_DIR = stateDir;
const lines: string[] = [];
const log = console.log;
console.log = (line: string) => lines.push(line);
try {
const fail = async () => {
throw new Error('boom\nstack line');
};
await runSafely('on-prompt', () => sessionId, fail);
await runSafely('on-prompt', () => sessionId, fail);
} finally {
console.log = log;
if (saved === undefined) delete process.env.SCTX_STATE_DIR;
else process.env.SCTX_STATE_DIR = saved;
}

expect(lines).toHaveLength(1);
expect(JSON.parse(lines[0]!).systemMessage).toContain('E_HOOK_FAILED');
expect(lines[0]).not.toContain('stack line');
});
});

describe('sctxCommand', () => {
const none = () => null;

it('prefers an explicit entry point, then an installed sctx, then bunx pinned to the release line', () => {
expect(sctxCommand({ sctxBin: '/x/index.ts' }, () => '/usr/bin/sctx')).toEqual(['bun', 'run', '/x/index.ts']);
expect(sctxCommand({}, () => '/usr/bin/sctx')).toEqual(['/usr/bin/sctx']);
expect(sctxCommand({}, none)).toEqual(['bunx', expect.stringMatching(/^structured-context@\d+\.\d+$/)]);
});
});
Loading
Loading