[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M74BNG2C082RCTF8KM0ECAZG":3,"skill-same:01M74BNG2C082RCTF8KM0ECAZG":88},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M74BNG2C082RCTF8KM0ECAZG","grund-init",null,"Use when bootstrapping or adopting grund in a repository, especially when the user wants an interactive guided setup for grund init, grund.toml, AGENTS.md, docs scaffolding, citation format, scan scope, output format, or Markdown link settings.","agent-grounds\u002Fgrund","agent-grounds","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F291984958?v=4","01M722MW9PSWR9KN2AS84FYY18","Agent Grounds","01M722MWAVHKVRT9K14CJMXW8M",4,"MIT","https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fcrates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: grund-init\ndescription: Use when bootstrapping or adopting grund in a repository, especially when the user wants an interactive guided setup for grund init, grund.toml, AGENTS.md, docs scaffolding, citation format, scan scope, output format, or Markdown link settings.\n---\n\n# grund init\n\nGuide the user through `grund` adoption. `grund init` itself is non-interactive, so this skill acts as the interactive wrapper: inspect the repository, recommend suitable settings, ask the user to confirm or override every option, write `grund.toml`, run `grund init`, then validate.\n\n## Fresh repository\n\nA repository is fresh when it has no `grund.toml`, at its root or under `.agents\u002F`, and no specs, decision records or tests to adopt. Say you are taking the defaults, and once the user agrees, run these three commands in order:\n\n```bash\ngrund init --scaffold --name \u003Cname> --agents-md   # add --claude, --gemini, … for each agent in use\ngrund init --check\ngrund check\n```\n\nSuccess is all three exiting `0`. On a fresh scaffold the last one also warns `nothing recognized` until the first declaration exists: that is expected, and nothing to fix. A fresh repository takes every default after that one confirmation, so that is the whole setup. Any repository that is not fresh is an adoption, and its per-option interview is the workflow `grund guide setup` prints.\n\n## Contents\n\nThis core, the section `setup`, holds Fresh repository, Contents, Workflow, Repo Analysis First, Asking Style, Init Questions, Existing Specs Adoption, Validation and Maintaining Declarations. The rest of the guide is ten reference sections, each printed on request by `grund guide \u003Cname>`; where this skill is installed as a directory, the same text is `references\u002F\u003Cname>.md`.\n\n- `grund guide config` (`references\u002Fconfig.md`): how to recommend each setting, then the config questions.\n- `grund guide citations` (`references\u002Fcitations.md`): the citation-directions question, version 1's `[citations]` and version 2's `[rules.citations]`, and its reference.\n- `grund guide languages` (`references\u002Flanguages.md`): language and repo-shape examples, version-2 sources, and moving from version 1.\n- `grund guide members` (`references\u002Fmembers.md`): splitting off a member.\n- `grund guide scoped-guidance` (`references\u002Fscoped-guidance.md`): where a version-2 config writes each row's guidance.\n- `grund guide schema` (`references\u002Fschema.md`): seeing the schema with `grund schema`.\n- `grund guide queries` (`references\u002Fqueries.md`): querying the structure.\n- `grund guide editor` (`references\u002Feditor.md`): wiring an editor to `grund-lsp`.\n- `grund guide integrations` (`references\u002Fintegrations.md`): clickable-citation integrations.\n- `grund guide rules` (`references\u002Frules.md`): writing chapter rules.\n\n`grund guide --full` prints this core and then every section, in this order.\n\n## Workflow\n\n1. Inspect the target repo before asking questions. Find existing specs, artifact types, roadmaps, changelogs, decisions, plans, tests, and agent instruction files before recommending anything.\n2. Present a short \"detected repo shape\" summary and recommended setup.\n3. If existing specs or spec-like artifacts are present, show the canonical `grund` artifact types beside the detected project-specific sections\u002Ftags\u002Fdocument classes, then ask which artifact model to adopt before writing config or refactoring docs.\n4. Fetch `grund guide config` for recommendations and questions except citation directions, and `grund guide citations` for those (version 1's `[citations]`, version 2's `[rules.citations]`). Directory copies: `references\u002Fconfig.md` and `references\u002Fcitations.md`. Ask each remaining question with a recommendation, repo evidence, pros, cons and when to choose otherwise.\n5. Write `grund.toml` from the analysis before `grund init`, so guidance reflects its grammar, marker, strict mode, kinds, artifact folders and scan scope. Without a config, run `grund init` first: its v2 starter writes only non-defaults — project name, kind rows, places and titles. Add only user-chosen overrides. Show `grund config show`: it prints effective settings with defaults in the config's version; copy a line into `grund.toml` to override it. Use `grund config explain` for that version's keys and each check code's fix. To adopt, `grund init --template=none` writes v2 config with no kinds. Before adding a kind, run check's offline help, `grund config explain '[schema.kinds.\u003CNAME>]'`, or `grund config explain schema.kinds` for the same child key rows. Add `[schema.kinds.\u003CKIND>]` tables with declaration `folders` or `files`, then rerun `grund init` to teach entrypoints.\n6. Run `grund init [path] [--name NAME] [--force]`, adding `--scaffold` only when the repo is fresh or the user selected a canonical-layout migration needing starter files. `--name` overrides the target config's `project_name` or, without one, its directory name. `--dry-run` previews; `--check` gates pre-commit\u002FCI without writes. `grund check` reports stale managed blocks; `init --check` also covers unjudged files, such as a member's workspace sections. A target needs a `.git`, `.hg`, `.jj` or `.svn` marker in itself or an ancestor; initialize its VCS first or pass `--no-vcs`. The home directory and machine-global agent files (`~\u002F.claude\u002FCLAUDE.md`, `~\u002F.codex\u002FAGENTS.md`, etc.) are refused regardless of flags: correct the target path. Follow `next:`, which names a configured kind and its home. For non-`FS` kinds, create a missing home manually: `--scaffold` lays the whole software-development starter, not that home alone, placing homes at its fixed places (a `REQ` row's folder), so it can miss one. Without `--scaffold`, no block means only that the home exists.\n7. Run `grund config validate [path]` and `grund check [path]`. At a workspace root, `config validate` names the config findings `check` names; `config show`, only its own config's.\n8. Summarize generated files, validation results, existing specs\u002Fartifacts found, and any follow-up cleanup.\n9. Optionally offer to wire the user's editor to the `grund-lsp` server (see Editor Setup: `grund guide editor`). Editor configuration is the user's one-time work, not something `grund init` writes — so only offer it, and prefer editor **user** settings over a per-repo config to make the configuration available across projects. User settings do not grant Workspace Trust; Editor Setup (`grund guide editor`) gives the VSCode \u002F VSCodium prerequisite.\n\n## Repo Analysis First\n\nUse `rg` and `rg --files` first. Prefer evidence from existing files over generic defaults.\n\nAnalyze:\n\n- Existing `AGENTS.md`, a `grund.toml` in either discovery location (root or `.agents\u002F`), and grund-style citations.\n- Documentation layout: `docs\u002F`, `e2e\u002F`, `spec\u002F`, `rfcs\u002F`, `adr\u002F`, `decisions\u002F`, `roadmap`, `changelog`.\n- Existing artifact types and their homes: specifications, requirements, RFCs, ADRs\u002Fdecisions, roadmaps, changelogs, plans, end-to-end fixtures, examples, package READMEs, generated reports, and runtime logs. Use these to choose configured places and source exclusions: version 2 uses `[schema.kinds.\u003CKIND>]` and `[schema.sources] exclude`; version 1 uses `[[kinds]]` and `[scan] include`\u002F`exclude`. Do not add generic folders when the repo already has project-specific artifact homes.\n- Source layout: `src\u002F`, `lib\u002F`, `crates\u002F`, `packages\u002F`, `apps\u002F`, `services\u002F`, `cmd\u002F`, `internal\u002F`, `pkg\u002F`, `test\u002F`, `tests\u002F`.\n- Languages from file extensions and manifests such as `Cargo.toml`, `package.json`, `pyproject.toml`, `go.mod`, `pom.xml`, `build.gradle`, `.csproj`, `Package.swift`, `Gemfile`, `composer.json`, `build.sbt`, `CMakeLists.txt`, `dbt_project.yml`.\n- Ignore\u002Fbuild\u002Fvendor directories from `.gitignore` and common generated paths.\n- Existing ID\u002Fcitation patterns, including headings and tokens that look like `FS-001-login`, `FS-login`, `ADR-001`, `RFC-42`, or `§FS-...`.\n- Existing rendered-doc target: GitHub default, GitLab, MkDocs, Pandoc, or unknown.\n- Whether this is a fresh repo, a docs-heavy repo, or an existing codebase adopting grund.\n\n## Asking Style\n\nAsk the user to confirm or change a recommendation, never a blank preference survey. Each prompt must include the recommended value, evidence from repo analysis, pros, cons, and when to choose a different value. Let the user accept the full set quickly while still seeing and overriding every option.\n\n## Init Questions\n\nAsk first:\n\n- Target path: default `.`\n- Project name: default target config value, then target directory basename\n- Artifact model when existing specs are detected: canonical `grund`, canonical core plus project-specific extras, or existing structure with citations\n- Template and starter files: `--template=software-development` (the default, canonical kinds) or `--template=none` (no kinds, for the existing-structure model); `--scaffold` to lay the starter files: default no for existing repos, yes for fresh repos\n- Existing file behavior: append\u002Fupdate default, or `--force`\n\n## Existing Specs Adoption\n\nWhen the repo already contains specs, requirements, ADRs, RFCs, design docs, plans, tests, or other spec-like artifacts, do not silently scaffold over them or refactor them into canonical `grund` folders. First show the user:\n\n- The canonical `grund` artifact types:\n  - `GRUND` — reason \u002F grounding doc\n  - `GOAL` — project goals\n  - `FS` — functional specs\n  - `AR` — architecture specs\n  - `DF` — functional decisions\n  - `DA` — architectural decisions\n  - `E2E` — executable scenarios\n  - `RM` — roadmap\n- The detected project-specific sections, tags, or document classes, such as `ADR`, `RFC`, `REQ`, `SPEC`, `DESIGN`, `PLAN`, `RUNBOOK`, or whatever the repo already uses.\n\nThen ask the user to choose one adoption model:\n\n| Option | When to recommend it | What the agent does |\n|---|---|---|\n| Canonical `grund` | Fresh or lightly documented repos, or users who explicitly want to reorganize around `grund` conventions. | Use `GRUND`, `GOAL`, `FS`, `AR`, `DF`, `DA`, `E2E`, and `RM` as the complete artifact model; add or refactor docs toward canonical homes only after user confirmation. |\n| Canonical core plus project-specific extras | Repos with useful existing ADRs\u002FRFCs\u002Frequirements but no clear behavior-vs-architecture backbone. | Use `GRUND`, `GOAL`, `FS`, and `AR` as the grounding backbone, then add custom kinds for project-specific artifacts: `[schema.kinds.\u003CKIND>]` in version 2, `[[kinds]]` in version 1. |\n| Existing structure with citations | Mature repos with a strong existing taxonomy or high migration cost. | Start from `grund init --template=none`, whose config declares no kinds; preserve current sections\u002Ftags\u002Fdocument classes, configure the kinds and their places around them (`[schema.kinds.\u003CKIND>]` in version 2; `[[kinds]]` and `[scan]` in version 1), and add `grund` citations\u002Fdeclarations without forcing canonical folders. |\n\nThe question should include a recommendation grounded in the inventory. Do not write `grund.toml`, run `grund init --scaffold`, move documents, rename headings, or add bulk citations until the user chooses the adoption model. Once selected, use the model to decide whether the setup is only config plus entrypoint refresh, or a broader docs refactor with a visible plan.\n\n## Validation\n\n`init` rule findings earn `1` even with current paths or `--dry-run`;\n`--check` also fails on pending paths. Read stdout findings separately from\nstderr paths: `grund guide rules` (`references\u002Frules.md`).\n\nAfter writing config, run:\n\n```bash\ngrund config validate .\ngrund init .\ngrund check .\ngrund check --full .\n```\n\nThe last line checks beyond configured source scope: `grund check .` uses the ordinary scope, while `grund check --full .` widens the walk to report unresolved references and section headings outside declaration bodies there ([the full-tree scope](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fdocs\u002Ffunctional-spec\u002FFS-check.md#13-the-full-tree-scope---full)). Version 1 scopes with `[scan] include`; version 2 uses configured places and the `code` complement. Source exclusions still apply: `[schema.sources] exclude` in v2, `[scan] exclude` in v1. For workspace boundaries and exclusions, run `grund guide members`.\n\nRead an unused warning's index-entry location alongside `grund refs \u003CID>` and\n`grund refs \u003CID> --summary`: refs retains the citation and labels it as an index\nentry, while check excludes it from use. In mixed summaries, read the annotated\nlines (and columns) as the excluded sites only. Keep a useful unused declaration\nor cite an actual dependency; do not invent a dependency just to silence the\nwarning. See the [checking guide](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fdocs\u002Fuser-facing\u002Fchecking.md#when-only-an-index-cites-a-declaration)\nand the [runnable example](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fexamples\u002Fauthored-citations\u002FREADME.md#when-only-the-index-cites-a-record).\n\n`grund refs` on an uncited ID notes `grund list --unused`: run that once, not `refs` per ID.\n\n`value mismatch for \u003CID> (component \u003Cpath>)`: keep the root citation, fix the whole literal ([values guide](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fdocs\u002Fuser-facing\u002Fvalues.md#equality-and-diagnostics)).\n\nIf a project needs its own grammar or independent check, follow\nSplitting off a member (`grund guide members`), then validate from the workspace root.\n\nFor an existing version-1 config, `grund config migrate --to 2` previews the\ntranslation. Read each listed comment's local reason and destination guidance:\nmoving a comment from the version-1 `include` key to the `[scan]` header still leaves it on a split\nattachment. To keep its prose, save it, explicitly authorize the listed drops\nwith `--write --drop-comments`, and re-add it at the named version-2 destination\nafter a successful write. Choose placement manually for a dropped setting or a\ncomment without a destination. When destinations are unavailable, repair and\npreview again first; comment consent clears no setting refusal or comparison\ngate. See the [migration report contract](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fdocs\u002Ffunctional-spec\u002FFS-config-migrate.md#22-stderr-is-the-report)\nand [runnable recovery walkthrough](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fexamples\u002Fmigrate\u002FREADME.md).\n\n## Maintaining Declarations\n\nBefore a rename or file move, run `grund refs \u003CID>` to find its citations.\nEdit the declaration and authored citation IDs, then run `grund fmt --write`\nfrom the config, project or workspace root. When cross-reference emission\napplies, fmt re-derives generated link destinations and anchors; the\nroot-scoped write also updates eligible section locks. Run `grund check` and\n`grund fmt --check`; commit lock changes. File-only moves keep ID-keyed lock\nnames. Do not hand-edit locks or expect fmt to replace authored IDs, repair\narbitrary URLs, or silently approve a protected section move. Its error names\nevery stale citation; `grund config explain section-address-changed` names\nthe fixes.\nA link the author wrote around a citation is theirs in every Markdown form:\ninline, wrapped, a reference, a definition, an autolink or HTML `\u003Ca>`. fmt\nneither rewrites nor follows it, so repair it by hand; its citation is still\nchecked. A citation-only image in a kind's index,\n`![§\u003CID>](x.png)`, is no entry: write the link beside it, or the ID is reported\nmissing ([authored links](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fdocs\u002Fuser-facing\u002Fstructure.md#linking-what-grund-does),\n[example](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fexamples\u002Fauthored-citations\u002FREADME.md)).\nDescribe a write by fmt's report, which names each rewrite, counts\nkinds and marks lock files deleted or created. Use the\n[maintenance guide](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fdocs\u002Fuser-facing\u002Fstructure.md#maintaining-declarations)\nand its [copy-based rename example](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fexamples\u002Frelative-sections-lock\u002FREADME.md).\n","# grund init\n\nGuide the user through `grund` adoption. `grund init` itself is non-interactive, so this skill acts as the interactive wrapper: inspect the repository, recommend suitable settings, ask the user to confirm or override every option, write `grund.toml`, run `grund init`, then validate.\n\n## Fresh repository\n\nA repository is fresh when it has no `grund.toml`, at its root or under `.agents\u002F`, and no specs, decision records or tests to adopt. Say you are taking the defaults, and once the user agrees, run these three commands in order:\n\n```bash\ngrund init --scaffold --name \u003Cname> --agents-md   # add --claude, --gemini, … for each agent in use\ngrund init --check\ngrund check\n```\n\nSuccess is all three exiting `0`. On a fresh scaffold the last one also warns `nothing recognized` until the first declaration exists: that is expected, and nothing to fix. A fresh repository takes every default after that one confirmation, so that is the whole setup. Any repository that is not fresh is an adoption, and its per-option interview is the workflow `grund guide setup` prints.\n\n## Contents\n\nThis core, the section `setup`, holds Fresh repository, Contents, Workflow, Repo Analysis First, Asking Style, Init Questions, Existing Specs Adoption, Validation and Maintaining Declarations. The rest of the guide is ten reference sections, each printed on request by `grund guide \u003Cname>`; where this skill is installed as a directory, the same text is `references\u002F\u003Cname>.md`.\n\n- `grund guide config` (`references\u002Fconfig.md`): how to recommend each setting, then the config questions.\n- `grund guide citations` (`references\u002Fcitations.md`): the citation-directions question, version 1's `[citations]` and version 2's `[rules.citations]`, and its reference.\n- `grund guide languages` (`references\u002Flanguages.md`): language and repo-shape examples, version-2 sources, and moving from version 1.\n- `grund guide members` (`references\u002Fmembers.md`): splitting off a member.\n- `grund guide scoped-guidance` (`references\u002Fscoped-guidance.md`): where a version-2 config writes each row's guidance.\n- `grund guide schema` (`references\u002Fschema.md`): seeing the schema with `grund schema`.\n- `grund guide queries` (`references\u002Fqueries.md`): querying the structure.\n- `grund guide editor` (`references\u002Feditor.md`): wiring an editor to `grund-lsp`.\n- `grund guide integrations` (`references\u002Fintegrations.md`): clickable-citation integrations.\n- `grund guide rules` (`references\u002Frules.md`): writing chapter rules.\n\n`grund guide --full` prints this core and then every section, in this order.\n\n## Workflow\n\n1. Inspect the target repo before asking questions. Find existing specs, artifact types, roadmaps, changelogs, decisions, plans, tests, and agent instruction files before recommending anything.\n2. Present a short \"detected repo shape\" summary and recommended setup.\n3. If existing specs or spec-like artifacts are present, show the canonical `grund` artifact types beside the detected project-specific sections\u002Ftags\u002Fdocument classes, then ask which artifact model to adopt before writing config or refactoring docs.\n4. Fetch `grund guide config` for recommendations and questions except citation directions, and `grund guide citations` for those (version 1's `[citations]`, version 2's `[rules.citations]`). Directory copies: `references\u002Fconfig.md` and `references\u002Fcitations.md`. Ask each remaining question with a recommendation, repo evidence, pros, cons and when to choose otherwise.\n5. Write `grund.toml` from the analysis before `grund init`, so guidance reflects its grammar, marker, strict mode, kinds, artifact folders and scan scope. Without a config, run `grund init` first: its v2 starter writes only non-defaults — project name, kind rows, places and titles. Add only user-chosen overrides. Show `grund config show`: it prints effective settings with defaults in the config's version; copy a line into `grund.toml` to override it. Use `grund config explain` for that version's keys and each check code's fix. To adopt, `grund init --template=none` writes v2 config with no kinds. Before adding a kind, run check's offline help, `grund config explain '[schema.kinds.\u003CNAME>]'`, or `grund config explain schema.kinds` for the same child key rows. Add `[schema.kinds.\u003CKIND>]` tables with declaration `folders` or `files`, then rerun `grund init` to teach entrypoints.\n6. Run `grund init [path] [--name NAME] [--force]`, adding `--scaffold` only when the repo is fresh or the user selected a canonical-layout migration needing starter files. `--name` overrides the target config's `project_name` or, without one, its directory name. `--dry-run` previews; `--check` gates pre-commit\u002FCI without writes. `grund check` reports stale managed blocks; `init --check` also covers unjudged files, such as a member's workspace sections. A target needs a `.git`, `.hg`, `.jj` or `.svn` marker in itself or an ancestor; initialize its VCS first or pass `--no-vcs`. The home directory and machine-global agent files (`~\u002F.claude\u002FCLAUDE.md`, `~\u002F.codex\u002FAGENTS.md`, etc.) are refused regardless of flags: correct the target path. Follow `next:`, which names a configured kind and its home. For non-`FS` kinds, create a missing home manually: `--scaffold` lays the whole software-development starter, not that home alone, placing homes at its fixed places (a `REQ` row's folder), so it can miss one. Without `--scaffold`, no block means only that the home exists.\n7. Run `grund config validate [path]` and `grund check [path]`. At a workspace root, `config validate` names the config findings `check` names; `config show`, only its own config's.\n8. Summarize generated files, validation results, existing specs\u002Fartifacts found, and any follow-up cleanup.\n9. Optionally offer to wire the user's editor to the `grund-lsp` server (see Editor Setup: `grund guide editor`). Editor configuration is the user's one-time work, not something `grund init` writes — so only offer it, and prefer editor **user** settings over a per-repo config to make the configuration available across projects. User settings do not grant Workspace Trust; Editor Setup (`grund guide editor`) gives the VSCode \u002F VSCodium prerequisite.\n\n## Repo Analysis First\n\nUse `rg` and `rg --files` first. Prefer evidence from existing files over generic defaults.\n\nAnalyze:\n\n- Existing `AGENTS.md`, a `grund.toml` in either discovery location (root or `.agents\u002F`), and grund-style citations.\n- Documentation layout: `docs\u002F`, `e2e\u002F`, `spec\u002F`, `rfcs\u002F`, `adr\u002F`, `decisions\u002F`, `roadmap`, `changelog`.\n- Existing artifact types and their homes: specifications, requirements, RFCs, ADRs\u002Fdecisions, roadmaps, changelogs, plans, end-to-end fixtures, examples, package READMEs, generated reports, and runtime logs. Use these to choose configured places and source exclusions: version 2 uses `[schema.kinds.\u003CKIND>]` and `[schema.sources] exclude`; version 1 uses `[[kinds]]` and `[scan] include`\u002F`exclude`. Do not add generic folders when the repo already has project-specific artifact homes.\n- Source layout: `src\u002F`, `lib\u002F`, `crates\u002F`, `packages\u002F`, `apps\u002F`, `services\u002F`, `cmd\u002F`, `internal\u002F`, `pkg\u002F`, `test\u002F`, `tests\u002F`.\n- Languages from file extensions and manifests such as `Cargo.toml`, `package.json`, `pyproject.toml`, `go.mod`, `pom.xml`, `build.gradle`, `.csproj`, `Package.swift`, `Gemfile`, `composer.json`, `build.sbt`, `CMakeLists.txt`, `dbt_project.yml`.\n- Ignore\u002Fbuild\u002Fvendor directories from `.gitignore` and common generated paths.\n- Existing ID\u002Fcitation patterns, including headings and tokens that look like `FS-001-login`, `FS-login`, `ADR-001`, `RFC-42`, or `§FS-...`.\n- Existing rendered-doc target: GitHub default, GitLab, MkDocs, Pandoc, or unknown.\n- Whether this is a fresh repo, a docs-heavy repo, or an existing codebase adopting grund.\n\n## Asking Style\n\nAsk the user to confirm or change a recommendation, never a blank preference survey. Each prompt must include the recommended value, evidence from repo analysis, pros, cons, and when to choose a different value. Let the user accept the full set quickly while still seeing and overriding every option.\n\n## Init Questions\n\nAsk first:\n\n- Target path: default `.`\n- Project name: default target config value, then target directory basename\n- Artifact model when existing specs are detected: canonical `grund`, canonical core plus project-specific extras, or existing structure with citations\n- Template and starter files: `--template=software-development` (the default, canonical kinds) or `--template=none` (no kinds, for the existing-structure model); `--scaffold` to lay the starter files: default no for existing repos, yes for fresh repos\n- Existing file behavior: append\u002Fupdate default, or `--force`\n\n## Existing Specs Adoption\n\nWhen the repo already contains specs, requirements, ADRs, RFCs, design docs, plans, tests, or other spec-like artifacts, do not silently scaffold over them or refactor them into canonical `grund` folders. First show the user:\n\n- The canonical `grund` artifact types:\n  - `GRUND` — reason \u002F grounding doc\n  - `GOAL` — project goals\n  - `FS` — functional specs\n  - `AR` — architecture specs\n  - `DF` — functional decisions\n  - `DA` — architectural decisions\n  - `E2E` — executable scenarios\n  - `RM` — roadmap\n- The detected project-specific sections, tags, or document classes, such as `ADR`, `RFC`, `REQ`, `SPEC`, `DESIGN`, `PLAN`, `RUNBOOK`, or whatever the repo already uses.\n\nThen ask the user to choose one adoption model:\n\n| Option | When to recommend it | What the agent does |\n|---|---|---|\n| Canonical `grund` | Fresh or lightly documented repos, or users who explicitly want to reorganize around `grund` conventions. | Use `GRUND`, `GOAL`, `FS`, `AR`, `DF`, `DA`, `E2E`, and `RM` as the complete artifact model; add or refactor docs toward canonical homes only after user confirmation. |\n| Canonical core plus project-specific extras | Repos with useful existing ADRs\u002FRFCs\u002Frequirements but no clear behavior-vs-architecture backbone. | Use `GRUND`, `GOAL`, `FS`, and `AR` as the grounding backbone, then add custom kinds for project-specific artifacts: `[schema.kinds.\u003CKIND>]` in version 2, `[[kinds]]` in version 1. |\n| Existing structure with citations | Mature repos with a strong existing taxonomy or high migration cost. | Start from `grund init --template=none`, whose config declares no kinds; preserve current sections\u002Ftags\u002Fdocument classes, configure the kinds and their places around them (`[schema.kinds.\u003CKIND>]` in version 2; `[[kinds]]` and `[scan]` in version 1), and add `grund` citations\u002Fdeclarations without forcing canonical folders. |\n\nThe question should include a recommendation grounded in the inventory. Do not write `grund.toml`, run `grund init --scaffold`, move documents, rename headings, or add bulk citations until the user chooses the adoption model. Once selected, use the model to decide whether the setup is only config plus entrypoint refresh, or a broader docs refactor with a visible plan.\n\n## Validation\n\n`init` rule findings earn `1` even with current paths or `--dry-run`;\n`--check` also fails on pending paths. Read stdout findings separately from\nstderr paths: `grund guide rules` (`references\u002Frules.md`).\n\nAfter writing config, run:\n\n```bash\ngrund config validate .\ngrund init .\ngrund check .\ngrund check --full .\n```\n\nThe last line checks beyond configured source scope: `grund check .` uses the ordinary scope, while `grund check --full .` widens the walk to report unresolved references and section headings outside declaration bodies there ([the full-tree scope](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fdocs\u002Ffunctional-spec\u002FFS-check.md#13-the-full-tree-scope---full)). Version 1 scopes with `[scan] include`; version 2 uses configured places and the `code` complement. Source exclusions still apply: `[schema.sources] exclude` in v2, `[scan] exclude` in v1. For workspace boundaries and exclusions, run `grund guide members`.\n\nRead an unused warning's index-entry location alongside `grund refs \u003CID>` and\n`grund refs \u003CID> --summary`: refs retains the citation and labels it as an index\nentry, while check excludes it from use. In mixed summaries, read the annotated\nlines (and columns) as the excluded sites only. Keep a useful unused declaration\nor cite an actual dependency; do not invent a dependency just to silence the\nwarning. See the [checking guide](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fdocs\u002Fuser-facing\u002Fchecking.md#when-only-an-index-cites-a-declaration)\nand the [runnable example](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fexamples\u002Fauthored-citations\u002FREADME.md#when-only-the-index-cites-a-record).\n\n`grund refs` on an uncited ID notes `grund list --unused`: run that once, not `refs` per ID.\n\n`value mismatch for \u003CID> (component \u003Cpath>)`: keep the root citation, fix the whole literal ([values guide](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fdocs\u002Fuser-facing\u002Fvalues.md#equality-and-diagnostics)).\n\nIf a project needs its own grammar or independent check, follow\nSplitting off a member (`grund guide members`), then validate from the workspace root.\n\nFor an existing version-1 config, `grund config migrate --to 2` previews the\ntranslation. Read each listed comment's local reason and destination guidance:\nmoving a comment from the version-1 `include` key to the `[scan]` header still leaves it on a split\nattachment. To keep its prose, save it, explicitly authorize the listed drops\nwith `--write --drop-comments`, and re-add it at the named version-2 destination\nafter a successful write. Choose placement manually for a dropped setting or a\ncomment without a destination. When destinations are unavailable, repair and\npreview again first; comment consent clears no setting refusal or comparison\ngate. See the [migration report contract](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fdocs\u002Ffunctional-spec\u002FFS-config-migrate.md#22-stderr-is-the-report)\nand [runnable recovery walkthrough](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fexamples\u002Fmigrate\u002FREADME.md).\n\n## Maintaining Declarations\n\nBefore a rename or file move, run `grund refs \u003CID>` to find its citations.\nEdit the declaration and authored citation IDs, then run `grund fmt --write`\nfrom the config, project or workspace root. When cross-reference emission\napplies, fmt re-derives generated link destinations and anchors; the\nroot-scoped write also updates eligible section locks. Run `grund check` and\n`grund fmt --check`; commit lock changes. File-only moves keep ID-keyed lock\nnames. Do not hand-edit locks or expect fmt to replace authored IDs, repair\narbitrary URLs, or silently approve a protected section move. Its error names\nevery stale citation; `grund config explain section-address-changed` names\nthe fixes.\nA link the author wrote around a citation is theirs in every Markdown form:\ninline, wrapped, a reference, a definition, an autolink or HTML `\u003Ca>`. fmt\nneither rewrites nor follows it, so repair it by hand; its citation is still\nchecked. A citation-only image in a kind's index,\n`![§\u003CID>](x.png)`, is no entry: write the link beside it, or the ID is reported\nmissing ([authored links](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fdocs\u002Fuser-facing\u002Fstructure.md#linking-what-grund-does),\n[example](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fexamples\u002Fauthored-citations\u002FREADME.md)).\nDescribe a write by fmt's report, which names each rewrite, counts\nkinds and marks lock files deleted or created. Use the\n[maintenance guide](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fdocs\u002Fuser-facing\u002Fstructure.md#maintaining-declarations)\nand its [copy-based rename example](https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fexamples\u002Frelative-sections-lock\u002FREADME.md).\n",{"name":5,"description":7},"main","cd22c9f4ffad48add7ffbc07d3338cd37597fc3e","crates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init",1,"https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund","https:\u002F\u002Fgithub.com\u002Fagent-grounds","Software development made automatic: the memory, the know-how, the cheap reads and the intake an agent needs to finish a matter with no human in the middle.","2026-11-15 02:23:34",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add agent-grounds\u002Fgrund --skill grund-init",{"tool":38,"command":39},"bunx","bunx skills add agent-grounds\u002Fgrund --skill grund-init",{"tool":41,"command":42},"pnpm","pnpm dlx skills add agent-grounds\u002Fgrund --skill grund-init","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fcrates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init\u002FSKILL.md",true,[46,52,56,60,64,68,72,76,80,84],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"references\u002Fcitations.md","REFERENCE","参考文档",12737,"https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fcrates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init\u002Freferences\u002Fcitations.md",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"references\u002Fconfig.md",14579,"https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fcrates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init\u002Freferences\u002Fconfig.md",{"path":57,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":58,"sourceHtmlUrl":59},"references\u002Feditor.md",1947,"https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fcrates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init\u002Freferences\u002Feditor.md",{"path":61,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":62,"sourceHtmlUrl":63},"references\u002Fintegrations.md",3640,"https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fcrates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init\u002Freferences\u002Fintegrations.md",{"path":65,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":66,"sourceHtmlUrl":67},"references\u002Flanguages.md",9998,"https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fcrates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init\u002Freferences\u002Flanguages.md",{"path":69,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":70,"sourceHtmlUrl":71},"references\u002Fmembers.md",4041,"https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fcrates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init\u002Freferences\u002Fmembers.md",{"path":73,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":74,"sourceHtmlUrl":75},"references\u002Fqueries.md",1978,"https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fcrates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init\u002Freferences\u002Fqueries.md",{"path":77,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":78,"sourceHtmlUrl":79},"references\u002Frules.md",24221,"https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fcrates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init\u002Freferences\u002Frules.md",{"path":81,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":82,"sourceHtmlUrl":83},"references\u002Fschema.md",950,"https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fcrates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init\u002Freferences\u002Fschema.md",{"path":85,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":86,"sourceHtmlUrl":87},"references\u002Fscoped-guidance.md",1992,"https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fcrates\u002Fgrund-core\u002Fassets\u002Fskills\u002Fgrund-init\u002Freferences\u002Fscoped-guidance.md",[89,95,100],{"skillNo":90,"name":91,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M74BNRPGC8C6ZWHHK4VX3501","review","https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Ftests\u002Fe2e\u002Fcases\u002Fcheck-non-citable-home-declaration\u002Frepo\u002Fskills\u002Freview\u002FSKILL.md",[],[],{"skillNo":96,"name":91,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":19},"01M74BNQHN1C57YRPG3QQB738P","https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Ftests\u002Fe2e\u002Fcases\u002Fcheck-citation-obligation-empty-citable\u002Frepo\u002Fskills\u002Freview\u002FSKILL.md",[],[],{"skillNo":101,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":19},"01M74BNKWMGVR10PEH6T2183C7","https:\u002F\u002Fgithub.com\u002Fagent-grounds\u002Fgrund\u002Fblob\u002Fmain\u002Fskills\u002Fgrund-init\u002FSKILL.md",[],[]]