Sw Init

---
name: sw-init
description: Use when the user asks to set up, initialize, scaffold or upgrade a second brain, LLM wiki or Superwiki vault in a project's docs folder, or invokes sw-init or sw:init.
---

# 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, and for which agents: Claude Code (`.claude/skills`), Codex and Copilot (`.agents/skills`). Recommend yes 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 this 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.

   ```bash
   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 folder, not one line per skill; and that the folder has 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`).

## 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-*/`, `.agents/skills/sw-*/`, when `skills` names an agent | 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 one of these folders |

## 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.