14 · install-existing-project

What this scenario proves

archon install is non-invasive: when run against a real existing project (Node + TypeScript), it adds Archon's files but does not touch a single byte of the host project's existing files.

Specifically, after install:

package.json, tsconfig.json, src/todo.ts, src/todo.test.ts — byte-identical to the fixture.
.archon/, .cursor/, tools/archon-cli/, scripts/ — newly added by the manifest projection.

This is the "host project respects me, I respect host project" contract that distinguishes Archon from frameworks that mutate package.json scripts, override tsconfig.json, or rewrite source files. Pair this with 13 · install-empty-dir to see that the delta between the two post-install trees is exactly the host project's pre-existing files — proving install is purely additive.

Test environment


Fixture	`fixtures/sandbox-node-ts`
IDE	Cursor
OS	macOS 14 / Ubuntu 22.04 / Windows 11
Archon source	local mirror of `docs/public/manifest.json`
Manifest version under test	v0.1.x
Language toolchain	Node 20.11+

Pre-conditions

Fixture copied — runner-managed.
No .archon/, no .cursor/.
Fixture's own files (package.json etc.) are intact.

Steps

text

1. Run:
     archon install --with=cli
2. Wait for the "install complete" summary line.

Expected outcome

Check	Expected
Exit code	0
`.archon/soul.md`	exists
`.cursor/commands/archon.md`	exists
`tools/archon-cli/`	exists (`--with=cli` was passed)
`package.json`	byte-identical to fixture
`tsconfig.json`	byte-identical to fixture
`src/todo.ts`	byte-identical to fixture
`src/todo.test.ts`	byte-identical to fixture
`.archon/drift.md` install rows	exactly 1

The byte-identity check is enforced by sha256_equals against the canonical fixture sha. If the fixture content ever changes, regenerate the sha values from git hash-object and update the spec block.

Demo recordings

Recording coming sooninstall-existing-project.mp4IDE chat-panel walkthrough

Will be replaced by docs/public/videos/install-existing-project.mp4 once recorded. See videos/README for upload conventions.

install-existing-project.cast

$ archon doctor .
[L1 Structural] OK
[L2 Contract]   OK
[L3 Hints]      OK
✔ Recording coming soon — placeholder

Will be replaced by docs/public/asciinema/install-existing-project.cast embedded via the asciinema-player web component. See asciinema/README for the recording command.

Run records

bash

node scripts/sandbox-run.mjs --only=install-existing-project

Started (UTC)	Manifest	Runner	Result	Duration	Notes	Record
`2026-06-08 08:17:11 UTC`	`v0.1.0`	cli	✅ passing	333 ms	—	JSON
`2026-06-07 07:10:16 UTC`	`v0.1.0`	cli	✅ passing	337 ms	—	JSON
`2026-06-06 06:34:40 UTC`	`v0.1.0`	cli	✅ passing	346 ms	—	JSON
`2026-06-05 07:14:06 UTC`	`v0.1.0`	cli	✅ passing	334 ms	—	JSON
`2026-06-04 07:56:43 UTC`	`v0.1.0`	cli	✅ passing	385 ms	—	JSON
`2026-06-03 08:24:17 UTC`	`v0.1.0`	cli	✅ passing	387 ms	—	JSON
`2026-06-02 08:00:51 UTC`	`v0.1.0`	cli	✅ passing	343 ms	—	JSON
`2026-06-01 08:40:45 UTC`	`v0.1.0`	cli	✅ passing	349 ms	—	JSON
`2026-05-31 07:02:23 UTC`	`v0.1.0`	cli	✅ passing	378 ms	—	JSON
`2026-05-30 06:27:52 UTC`	`v0.1.0`	cli	✅ passing	343 ms	—	JSON
`2026-05-29 06:59:39 UTC`	`v0.1.0`	cli	✅ passing	371 ms	—	JSON
`2026-05-28 06:59:33 UTC`	`v0.1.0`	cli	✅ passing	354 ms	—	JSON
`2026-05-27 07:09:41 UTC`	`v0.1.0`	cli	✅ passing	353 ms	—	JSON
`2026-05-26 06:52:08 UTC`	`v0.1.0`	cli	✅ passing	321 ms	—	JSON
`2026-05-25 07:20:21 UTC`	`v0.1.0`	cli	✅ passing	352 ms	—	JSON
`2026-05-24 06:41:52 UTC`	`v0.1.0`	cli	✅ passing	340 ms	—	JSON
`2026-05-23 06:16:49 UTC`	`v0.1.0`	cli	✅ passing	342 ms	—	JSON
`2026-05-22 06:54:17 UTC`	`v0.1.0`	cli	✅ passing	344 ms	—	JSON
`2026-05-21 06:58:03 UTC`	`v0.1.0`	cli	✅ passing	333 ms	—	JSON
`2026-05-20 06:53:37 UTC`	`v0.1.0`	cli	✅ passing	348 ms	—	JSON
`2026-05-19 06:53:17 UTC`	`v0.1.0`	cli	✅ passing	341 ms	—	JSON
`2026-05-18 07:01:46 UTC`	`v0.1.0`	cli	✅ passing	360 ms	—	JSON
`2026-05-17 06:27:35 UTC`	`v0.1.0`	cli	✅ passing	343 ms	—	JSON
`2026-05-16 06:04:39 UTC`	`v0.1.0`	cli	✅ passing	337 ms	—	JSON
`2026-05-15 06:37:58 UTC`	`v0.1.0`	cli	✅ passing	346 ms	—	JSON
`2026-05-14 06:28:56 UTC`	`v0.1.0`	cli	✅ passing	381 ms	—	JSON
`2026-05-13 06:30:24 UTC`	`v0.1.0`	cli	✅ passing	313 ms	—	JSON
`2026-05-12 06:19:00 UTC`	`v0.1.0`	cli	✅ passing	345 ms	—	JSON
`2026-05-11 06:45:34 UTC`	`v0.1.0`	cli	✅ passing	310 ms	—	JSON
`2026-05-10 06:16:44 UTC`	`v0.1.0`	cli	✅ passing	369 ms	—	JSON
`2026-05-09 05:52:37 UTC`	`v0.1.0`	cli	✅ passing	400 ms	—	JSON
`2026-05-08 05:33:35 UTC`	`v0.1.0`	cli	✅ passing	363 ms	—	JSON
`2026-05-07 11:01:02 UTC`	`v0.1.0`	cli	✅ passing	323 ms	—	JSON
`2026-05-07 09:54:53 UTC`	`v0.1.0`	cli	✅ passing	338 ms	—	JSON
`2026-05-07 09:45:11 UTC`	`v0.1.0`	cli	✅ passing	555 ms	—	JSON
`2026-05-07 06:15:44 UTC`	`v0.1.0`	cli	✅ passing	282 ms	—	JSON
`2026-05-06 11:45:36 UTC`	`v0.1.0`	cli	✅ passing	332 ms	—	JSON
`2026-05-06 11:44:05 UTC`	`v0.1.0`	cli	✅ passing	357 ms	—	JSON
`2026-05-06 11:19:25 UTC`	`v0.1.0`	cli	✅ passing	364 ms	—	JSON

Known limitations

Only checks four host files for byte-identity. A larger fixture (e.g. a real Vite + React skeleton) would need a directory-tree hash — out of scope until an adopter actually reports a mutation bug on a richer tree.
Does not run npm install && npm run validate post-install. That belongs to scenario 01 (install-cursor-node) which also verifies the validation chain.

Cross-references

Protocol page: /setup/install
Companion scenario: 13 · install-empty-dir — install without any host files.
Install matrix: Install Matrix
Sibling: 01 · install-cursor-node — same fixture, focuses on validate-chain not host-file preservation.

json

{
  "runnable": "cli",
  "fixture": "fixtures/sandbox-node-ts",
  "ide_platform": "cursor",
  "prerequisites": [
    {
      "name": "drop sandbox check helper",
      "write_file": {
        "path": "__sb-check.cjs",
        "content": "const fs=require('fs');const op=process.argv[2];const args=process.argv.slice(3);if(op==='drift-install-count'){const want=Number(args[0]);const c=fs.readFileSync('.archon/drift.md','utf8');const m=c.match(/^## install /gm);const n=m?m.length:0;if(n!==want){console.error('drift install rows: want',want,'got',n);process.exit(1)}process.exit(0)}if(op==='no-backup-dir'){const found=fs.readdirSync('.').some(function(x){return x.indexOf('.archon-backup-')===0});if(found){console.error('unexpected .archon-backup-*');process.exit(1)}process.exit(0)}if(op==='has-backup-dir'){const found=fs.readdirSync('.').some(function(x){return x.indexOf('.archon-backup-')===0});if(!found){console.error('expected .archon-backup-* missing');process.exit(1)}process.exit(0)}if(op==='pkg-name-equals'){const p=require('./package.json');if(p.name!==args[0]){console.error('package.json name mutated:',p.name);process.exit(1)}process.exit(0)}if(op==='file-includes'){const text=fs.readFileSync(args[0],'utf8');if(text.indexOf(args[1])===-1){console.error(args[0],'missing',args[1]);process.exit(1)}process.exit(0)}if(op==='drift-modules-excludes'){const c=fs.readFileSync('.archon/drift.md','utf8');const re=new RegExp('^- Modules:.*\\\\b'+args[0]+'\\\\b','m');if(re.test(c)){console.error(args[0],'unexpectedly listed');process.exit(1)}process.exit(0)}console.error('unknown op:',op);process.exit(2);\n"
      }
    }
  ],
  "steps": [
    {
      "name": "archon install --with=cli",
      "cli": "install",
      "flags": ["--with=cli"]
    }
  ],
  "assertions": [
    { "file_exists": ".archon/soul.md" },
    { "file_exists": ".cursor/commands/archon.md" },
    { "dir_exists": "tools/archon-cli" },
    { "file_exists": "package.json" },
    { "file_exists": "src/todo.ts" },
    { "file_exists": "src/todo.test.ts" },
    { "cmd_zero": ["node", "__sb-check.cjs", "pkg-name-equals", "acme-todos"] },
    { "cmd_zero": ["node", "__sb-check.cjs", "file-includes", "src/todo.ts", "Todo"] },
    { "cmd_zero": ["node", "__sb-check.cjs", "drift-install-count", "1"] },
    { "cmd_zero": ["python3", "scripts/archon-check.py", "--root", "."] }
  ],
  "notes": "Asserts install is non-invasive on a real Node+TS project: package.json identity field unchanged, source file content preserved, exactly one install row in drift."
}

14 · install-existing-project ​

What this scenario proves ​

Test environment ​

Pre-conditions ​

Steps ​

Expected outcome ​

Demo recordings ​

Run records ​

Known limitations ​

Cross-references ​