sw-init

Turns docs/ into a Superwiki vault: an LLM-maintained wiki that is also an Obsidian vault, with an optional task module. A script does the scaffolding; do not create the files by hand.

The vault is always <project root>/docs. Run every command below from the project root. <skill-dir> is the directory this SKILL.md is in.

Steps

1. Check Node: node --version must be 18 or newer. If not, go to "Without Node".

2. Upgrade or new? If docs/.sw/config.json exists this is an upgrade: skip step 3 and run the script with no flags; it reuses the saved choices.

3. Ask the user, in one message (new vault only):

   • Task module on or off. Recommend on when the project is mainly code, off for a pure knowledge base.
   • If on, the area prefixes for task ids (M-01, B-01). Recommend the single default area T unless the project already has separately named parts. Area names are optional labels; do not ask for them separately.
   • Whether the Superwiki skills should also be kept in the repository, as sw-<name> folders, and for which agents: Claude Code (.claude/skills), Codex and Copilot (.agents/skills). Recommend yes, for the agents the team uses, when cloud agents will work on the repository (Claude Code on the web, Codex cloud, the Copilot coding agent): they start from a clone, see no home folder, and so have only the skills that are committed. Otherwise recommend no. Leave the question out when <skill-dir> is inside the project: the skills are in the repository already.

4. Run the script, with the flags that match the answers. --skills takes the agents, comma-separated: claude, codex, copilot or all. Without it no skills are copied.

   node <skill-dir>/scripts/init.mjs --tasks                               # tasks on, default area T
   node <skill-dir>/scripts/init.mjs --tasks --areas "M=Mobile,B=Backend"  # tasks on, named areas
   node <skill-dir>/scripts/init.mjs --no-tasks                            # wiki only
   node <skill-dir>/scripts/init.mjs --tasks --skills claude,codex         # tasks on, skills in the repository for Claude Code and Codex
   node <skill-dir>/scripts/init.mjs                                       # upgrade
   

5. Check: run node docs/.sw/sw.mjs lint. A new vault reports 0 errors, 0 warnings. On an upgrade, findings are about the user's existing pages: show them, do not fix them unasked.

6. Report to the user from the script's output. Each line starts with a status:

   Status	Say
   created, updated	what is new or changed
   created, updated for .claude/skills/sw-*/ or .agents/skills/sw-*/	that the skills are in the repository, in one sentence naming the folders, not one line per skill; and that the folders have to be committed before a clone or a cloud agent has them
   kept, unchanged	that user content and settings were not touched (one sentence, no list)
   kept ... (not installed by Superwiki)	that a skill folder of that name was already there and was left as it is; name it. npx superwiki install --project . --force <targets> replaces it, if the user wants that
   missing	that this Superwiki build lacks the file; name it, and do not point the user at it
   note about CLAUDE.md	offer to add the @AGENTS.md line. Add it only after the user agrees to that specific change
   note "skills in the repository left alone"	that the script ran from the repository's own copy of the skills and so did not update them; give the command from the note
   "docs/ already had content"	that content is untouched and outside the vault; sw-migrate converts it

   End with how to look at the result: open docs/ as an Obsidian vault, or open docs/viewer.html in Chrome or Edge and pick the project folder (only if the viewer was not reported missing). When the answers name Codex or Copilot (the skills question answered yes, or the user said they work with one of them), add that Codex and Copilot run the planner, implementer and reviewer only through agent files in the project, which sw-config writes: sw-config sync --tools codex, copilot or both, once, before the first sw-plan or sw-implement there.

What the script guarantees

File	On re-run
docs/index.md, docs/log.md, everything in raw/, wiki/, tasks/, plans/	kept
docs/.sw/sw.mjs, docs/.sw/templates/, docs/viewer.html	replaced with this version
AGENTS.md	only the Superwiki block (from the sw:start comment to the sw:end comment) is replaced
docs/.sw/config.json	areas, models and the agents whose skills are kept in the repository (skills) stay as saved unless new flags are passed
.claude/skills/sw-*/ and .agents/skills/sw-*/, when skills names their agents	a folder Superwiki installed is replaced with this version; any other folder of that name is kept. Nothing is deleted, also not after --no-skills. Left alone when the script runs from that folder

Without Node

The script and docs/.sw/sw.mjs need Node 18 or newer. If node is missing or older, say so and stop; continue by hand only if the user asks for that. By hand: create docs/{raw/assets,wiki} (plus tasks, plans), copy assets/templates/ to docs/.sw/templates/ and assets/viewer.html to docs/, write index.md and log.md as the script would, and paste assets/agents-block.md into AGENTS.md with the {{...}} lines resolved. Tell the user the sw.mjs commands in that block will not work until Node is installed.