Skip to content

Onboarding: discover space-like content in a project and set up space configuration #145

Open

Description

@mindsocket

Summary

Give new users a guided path from "installed sctx and the Claude Code plugin" to "a configured space validating real content", without having to write config by hand first.

User journey

  1. Someone is working on a project that already contains somewhat structured markdown: typed frontmatter, a knowledge wiki, an Open Knowledge Format bundle (Bundle an Open Knowledge Format (OKF) schema #143), and so on.
  2. They discover structured-context and install the CLI and the Claude Code plugin.
  3. An onboarding skill or command (for example /init-space) scans the project for space-like content:
    • directories of markdown with consistent frontmatter keys or type values;
    • OKF bundles (a root index.md with okf_version);
    • matches against bundled schemas.
  4. It proposes candidate spaces, with a suggested schema, path and type inference settings, and writes the config the user accepts.
  5. It runs a first validation and summarises the results, so the user sees the size of the gap before anything enforces it.

Staged enablement

Existing content may have many violations. Onboarding should not leave the user with hooks reacting to all of it straight away.

Open questions

  • Skill, slash command, or a CLI command (sctx init) that the skill wraps? A CLI command would also serve non-Claude users.
  • Where config is written: project-local config.json, user config, or ask.
  • How far detection should go: suggest a bundled schema only, or draft a local schema from observed frontmatter.

Related: #89 (skill initialisation), #76 (validation anywhere), #80, #92

Activity

  1. mindsocket commented on Oct 22, 2026

    @mindsocket
    OwnerAuthor

    Scope extension: from discovery to inferring a schema and importing content

    #145 covers discovering space-like markdown and proposing a configuration. Two parts of the same journey are not covered yet, and the open question about drafting a local schema from observed frontmatter is the start of the first one.

    1. Infer a schema from existing content. Profile a directory (frontmatter key frequencies, folder-to-type candidates, heading shapes, link patterns), propose a draft schema or the closest bundled one, then check the proposal against the content. Violations from the first validation should feed the next proposal. #117 is the consumer side of that loop.

    2. Bring in content that isn't markdown yet. Pull from another system (a wiki, an issue tracker, documents), map fields onto the target schema, emit nodes, then validate.

    Approach, skills first.

    • A source-agnostic family of skills owns the workflow: profile, propose, map, extract, validate, iterate. They carry the structured-context knowledge: target schema, field mapping, wikilink and embedded-node conventions.
    • Physical access to a source uses whatever the environment already provides (an MCP server, a CLI, an API script), not a dedicated plugin API.
    • A deterministic read-only profile step is added only if agent-only profiling proves non-repeatable or too costly on large content sets. A new CLI surface is not the starting point.
    • Source-specific skills live outside this repository.

    Open questions

    • Is sctx init needed, or does the skill do everything using existing commands?
    • Where do inferred mappings live, so a re-run is repeatable (config, or a file beside the schema)?
    • How do we evaluate these skills? This ties into Create evals for the structured-context agent skill #38.

    Related: #117, #38, #37, #89

  2. mindsocket commented on Oct 26, 2026

    @mindsocket
    OwnerAuthor

    Phase 1 is in draft PR #175: .sctx.json discovery, sctx spaces add, error codes in sctx spaces --json, a SessionStart preflight, and a setup-space skill.

    Decided along the way:

    • One config per collection of notes, nearest wins, no merging by location. includeSpacesFrom is the way to combine configs.
    • Creating a config needs an explicit target (--config <folder>/.sctx.json or --global); there is no default to the working folder.
    • Hooks stay silent on a broken setup and the session start reports it once, with a code the skill can troubleshoot.

    Later phases:

    • Per-edit hooks finding a config from the edited file's path
    • Commands to edit or remove a space
    • Map view of a space (navigator)
    • Starting from a template when there is no content
    • Configurable rule severity (#92) for noisy rules
    • Hooks that don't need Bun

    The Obsidian plugin side is on a separate branch of obsidian-structured-context and needs this released first.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions