Add KOS to an existing vault

Goal and prerequisites

Preserve existing notes while adding a supported KOS layer. Make a full backup outside the vault, verify it opens, and create a separate test copy. Pause sync and close editors before applying changes.

Choose the correct route

An ordinary Obsidian vault, an existing Community vault, and a Pro vault are different starting points. Inspect the existing installation records before choosing a command.

• Plain Obsidian + Community: use enhance.
• Existing supported Community: use upgrade.
• Pro or a supported transition to Pro: use the Pro guided flow.

Enhance ordinary Obsidian with Community

From the extracted Starter Kit 1.2.0 folder, replace PATH-TO-TEST-COPY with the actual copied vault directory:

./install.ps1 -Target 'PATH-TO-TEST-COPY' -Operation enhance -Mode minimal -DryRun
./install.ps1 -Target 'PATH-TO-TEST-COPY' -Operation enhance -Mode minimal -Approve
./install.ps1 -Target 'PATH-TO-TEST-COPY' -Operation validate

Minimal mode adds the KOS layer. Complete mode can add missing numbered domains. Existing notes and .obsidian are preserved; modified files are preserved or proposed for review rather than globally overwritten.

Resolve Community conflicts explicitly

Read the dry-run plan and use its exact vault-relative paths. Save a JSON object as decisions.json outside the target vault. For example, when the plan lists a customized AGENTS.md that you want to retain:

{
  "AGENTS.md": "keep"
}

From the extracted Starter Kit folder, preview the decisions before applying them:

./install.ps1 -Target 'PATH-TO-TEST-COPY' -Operation enhance -Mode minimal -Decisions './decisions.json' -DryRun
./install.ps1 -Target 'PATH-TO-TEST-COPY' -Operation enhance -Mode minimal -Decisions './decisions.json' -Approve
./install.ps1 -Target 'PATH-TO-TEST-COPY' -Operation validate

The decision values are keep, skip, propose, adopt and replace; their applicability depends on the conflict. replace is limited to previously tracked managed or managed-customizable files, not user knowledge. adopt is for an explicitly reviewed alternate capability path. These choices do not override security, edition or version blocks. Inspect proposals and edit them manually when a merge is needed. The Starter Kit 1.2 operation guide defines the interface.

The installer checks file targets, not every Obsidian behavior. Heading/block targets, aliases, plugin-specific links and reference-style Markdown still need manual review. Test representative links and plugins in the copied vault.

Verify before touching the original

Open the copied vault. Check note links, attachments, templates, selected adapters and the installation report. Complete the first useful task. Compare the proposed changes with your actual workflows before authorizing the original vault.

If inspection blocks the change

Keep the blocker report. Resolve exact conflicts on the copy. Do not delete installer state or force a package for another edition. Upgrade guidance covers unsupported older vaults and manual review boundaries.