Skip to content
This repository was archived by the owner on Apr 26, 2026. It is now read-only.

Commit 39fc33f

Browse files
settletop-nilessettletop-niles
authored
Update Wiki (#20)
Co-authored-by: settletop-niles <settletop-niles@users.noreply.github.com>
1 parent ff19727 commit 39fc33f

9 files changed

Lines changed: 334 additions & 42 deletions

‎docs/wiki/Architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
High-level pipeline:
44

55
1. Writers: The extension instruments editor and file system events and appends PCM events to `.coderoot/v1/files/<rel>.xform.jsonl` (rotated by size).
6-
2. Snapshot builder: `snapshotBuilder.buildSnapshotFromJournal()` consumes rotated journal files and materializes a per-file snapshot under `.coderoot/v1/snapshots/<rel>.pcm.json` (schema_version 1.1.7).
6+
2. Snapshot builder: `snapshotBuilder.buildSnapshotFromJournal()` consumes rotated journal files and materializes a per-file snapshot under `.coderoot/v1/snapshots/<rel>.pcm.json` (schema_version 1.1.8).
77
3. Index & manifest: `indexManifest.writeManifest()` writes a small repository-level manifest used by reporters and maintenance tasks.
88
4. Reporter: `report.generateReport()` locates `assets/ci-reporter.mjs` and executes `generateReport(workspaceRoot)` to produce JSON and Markdown outputs.
99

‎docs/wiki/Commands.md‎

Lines changed: 94 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -5,42 +5,115 @@ This page lists primary CodeRoot.ai commands available in VS Code and what they
55

66
Commands and quick examples
77

8-
1. coderoot.openQuickMenu
8+
1. coderoot.settingsQuickMenu
99

10-
- Purpose: Open the CodeRoot quick menu (safe when not initialized).
11-
- Use from: VS Code Command Palette (CodeRoot: Quick Menu).
10+
- Purpose: CodeRoot: Settings / Quick Menu
11+
- Use from: VS Code Command Palette (CodeRoot: Settings / Quick Menu)
1212

13-
2. coderoot.initProject
13+
2. coderoot.toggleVisibility
1414

15-
- Purpose: Initialize the workspace for CodeRoot. Creates `.coderoot/config.json` and baseline state.
16-
- Example: run from Command Palette: "CodeRoot: Initialize CodeRoot".
15+
- Purpose: CodeRoot: Toggle .coderoot Visibility
16+
- Use from: VS Code Command Palette (CodeRoot: Toggle .coderoot Visibility)
1717

18-
3. coderoot.toggleJournal
18+
3. coderoot.openFolder
1919

20-
- Purpose: Enable/disable journaling (persisted in `.coderoot`). Requires initialization.
20+
- Purpose: CodeRoot: Open .coderoot Folder
21+
- Use from: VS Code Command Palette (CodeRoot: Open .coderoot Folder)
2122

22-
4. coderoot.setInventoryModeModified / coderoot.setInventoryModeAll
23+
4. coderoot.initProject
2324

24-
- Purpose: Switch inventory indexing mode between `modified` and `all`.
25+
- Purpose: CodeRoot: Initialize CodeRoot
26+
- Use from: VS Code Command Palette (CodeRoot: Initialize CodeRoot)
2527

26-
5. coderoot.toggleVisibility
28+
5. coderoot.toggleJournal
2729

28-
- Purpose: Toggle `.coderoot` visibility in explorer (workspace or per-folder).
30+
- Purpose: CodeRoot: Toggle Logging
31+
- Use from: VS Code Command Palette (CodeRoot: Toggle Logging)
2932

30-
6. coderoot.autoCommit / coderoot.autoCommitDryRun
33+
6. coderoot.migrateLegacyPCM
3134

32-
- Purpose: Auto-commit helper (dry-run shows which files would be staged).
33-
- Example (dry-run): the dry-run command writes details to the extension output channel — use `coderoot.autoCommitDryRun`.
35+
- Purpose: CodeRoot: Migrate Legacy PCM Journals
36+
- Use from: VS Code Command Palette (CodeRoot: Migrate Legacy PCM Journals)
3437

35-
7. coderoot.generateReport
38+
7. coderoot.enableJournal
3639

37-
- Purpose: Generate JSON + Markdown report via `assets/ci-reporter.mjs`.
38-
- Example (from command): run `CodeRoot: Generate Report` in the Command Palette. The extension will prompt to open the generated Markdown.
40+
- Purpose: CodeRoot: Enable Logging
41+
- Use from: VS Code Command Palette (CodeRoot: Enable Logging)
3942

40-
8. Identity & migration utilities
43+
8. coderoot.disableJournal
4144

42-
- `coderoot.consolidateIdentitiesNow`, `coderoot.runIdentitySweep`, `coderoot.trustIdentitySeeds`, `coderoot.migrateSnapshotsPerUser`, `coderoot.migrateLegacyPCM`
43-
- Purpose: Maintenance and migration tasks. `migrateLegacyPCM` prompts for Dry-run vs Apply and can use `scripts/migrate-legacy-pcm.mjs`.
45+
- Purpose: CodeRoot: Disable Logging
46+
- Use from: VS Code Command Palette (CodeRoot: Disable Logging)
47+
48+
9. coderoot.setInventoryModeModified
49+
50+
- Purpose: CodeRoot: Inventory Mode — Modified
51+
- Use from: VS Code Command Palette (CodeRoot: Inventory Mode — Modified)
52+
53+
10. coderoot.setInventoryModeAll
54+
55+
- Purpose: CodeRoot: Inventory Mode — All
56+
- Use from: VS Code Command Palette (CodeRoot: Inventory Mode — All)
57+
58+
11. coderoot.toggleInventoryMode
59+
60+
- Purpose: CodeRoot: Toggle Inventory Mode
61+
- Use from: VS Code Command Palette (CodeRoot: Toggle Inventory Mode)
62+
63+
12. coderoot.generateReport
64+
65+
- Purpose: CodeRoot: Generate Report
66+
- Use from: VS Code Command Palette (CodeRoot: Generate Report)
67+
68+
13. coderoot.consolidateIdentitiesNow
69+
70+
- Purpose: CodeRoot: Consolidate Identities Now
71+
- Use from: VS Code Command Palette (CodeRoot: Consolidate Identities Now)
72+
73+
14. coderoot.trustIdentitySeeds
74+
75+
- Purpose: CodeRoot: Trust Identity Seeds
76+
- Use from: VS Code Command Palette (CodeRoot: Trust Identity Seeds)
77+
78+
15. coderoot.toggleCiMaintenance
79+
80+
- Purpose: CodeRoot: Toggle CI Scripts Maintenance
81+
- Use from: VS Code Command Palette (CodeRoot: Toggle CI Scripts Maintenance)
82+
83+
16. coderoot.viewKeybindingConflicts
84+
85+
- Purpose: CodeRoot: View Keybinding Conflicts
86+
- Use from: VS Code Command Palette (CodeRoot: View Keybinding Conflicts)
87+
88+
17. coderoot.intercept.editor_action_clipboardPasteAction
89+
90+
- Purpose: CodeRoot: Intercept Paste
91+
- Use from: VS Code Command Palette (CodeRoot: Intercept Paste)
92+
93+
18. coderoot.intercept.editor_action_formatDocument
94+
95+
- Purpose: CodeRoot: Intercept Format Document
96+
- Use from: VS Code Command Palette (CodeRoot: Intercept Format Document)
97+
98+
19. coderoot.intercept.editor_action_formatSelection
99+
100+
- Purpose: CodeRoot: Intercept Format Selection
101+
- Use from: VS Code Command Palette (CodeRoot: Intercept Format Selection)
102+
103+
20. coderoot.intercept.github_copilot_acceptSuggestion
104+
105+
- Purpose: CodeRoot: Intercept CoPilot Accept Suggestion
106+
- Use from: VS Code Command Palette (CodeRoot: Intercept CoPilot Accept Suggestion)
107+
108+
21. coderoot.intercept.github_copilot_acceptInlineCompletion
109+
110+
- Purpose: CodeRoot: Intercept CoPilot Accept Inline Completion
111+
- Use from: VS Code Command Palette (CodeRoot: Intercept CoPilot Accept Inline Completion)
112+
113+
22. coderoot.intercept.editor_action_inlineSuggest_commit
114+
115+
- Purpose: CodeRoot: Intercept Inline Suggest Commit
116+
- Use from: VS Code Command Palette (CodeRoot: Intercept Inline Suggest Commit)
44117

45118
Notes & verification
46119

‎docs/wiki/Configuration.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ Aggregation (rollup)
6161
| aggregation.merge_window_ms | Merge nearby edits | ~1500 | Increase for chatty tools |
6262
| aggregation.format_merge_ms | Merge formatter edits | ~3000 | As above |
6363
| aggregation.command_merge_ms | Merge command-triggered edits | ~3000 | As above |
64-
| aggregation.ai_block_min_chars | Threshold for large AI apply | ~200 chars | Tweak for your AI usage |
64+
| aggregation.ai_block_min_chars | ~~Threshold for large AI apply~~ **DEPRECATED: Metadata-only** | ~200 chars | No longer used for classification |
6565
| aggregation.ai_prewindow_ms_for_large_apply | Pre-window for large AI apply | ~5000 ms | Advanced tuning |
6666
| aggregation.ai_merge_ms_for_large_apply | Merge window for large AI apply | ~10000 ms | Advanced tuning |
6767
| aggregation.human_high_tcs_threshold | High typing-confidence threshold | ~0.6 | Advanced tuning |
@@ -87,6 +87,7 @@ Report (presentation)
8787
| report.version_mix.threshold_pct | Threshold for mixed versions | ~10 | Policy-based |
8888
| report.version_mix.grace_days | Grace period before flagging | ~14 | Policy-based |
8989
| report.version_mix.legacy_versions| List of legacy versions | e.g., 1.1.3–1.1.5 | As needed |
90+
| report.current_version | Current release version (string) | e.g., 1.1.7 — should correspond to active config schema version | Optional |
9091
| report.timeModel | Time attribution model | constant, weighted | Preference |
9192
| report.weights.* | Weights for time model | human/ai_apply/tooling/journal | Advanced |
9293
| report.toolingBurst.enabled | Cap tooling bursts | false/true | Enable to cap tooling time |
@@ -142,12 +143,12 @@ Detectors (format/paste/tooling/AI)
142143
| detectors.format_after_save_window_ms | Window after save for format detection | ~350 ms | Tuning only |
143144
| detectors.tooling_multi_range_min | Multiple ranges → likely tooling | ~5 | Tuning only |
144145
| detectors.tooling_scatter_min | Scattered edits → likely tooling | ~16 | Tuning only |
145-
| detectors.paste_min_chars | Minimum chars to consider a paste | ~30 | Tuning only |
146+
| detectors.paste_min_chars | ~~Minimum chars to consider a paste~~ **DEPRECATED: Metadata-only** | ~30 | No longer used for classification |
146147
| detectors.paste_clipboard_probe | Clipboard probe mode | off, hash | Keep hash |
147148
| detectors.paste_clipboard_window_ms | Window to link clipboard to paste | ~1500 ms | Tuning only |
148149
| detectors.paste_hash_algo | Hash algorithm for clipboard | sha256 | Fixed |
149-
| detectors.ai_block_min_chars | Min chars to treat as AI block | ~120 | Tuning only |
150-
| detectors.ai_dual_block_chars | Second threshold for dual blocks | ~80 | Tuning only |
150+
| detectors.ai_block_min_chars | ~~Min chars to treat as AI block~~ **DEPRECATED: Metadata-only** | ~120 | No longer used for classification |
151+
| detectors.ai_dual_block_chars | ~~Second threshold for dual blocks~~ **DEPRECATED: Metadata-only** | ~80 | No longer used for classification |
151152
| detectors.ai_structure_threshold | Structure threshold | ~0.7 | Tuning only |
152153
| detectors.stream_adaptive | Adaptive streaming detection | true/false | Advanced |
153154
| detectors.stream_lines_min | Min lines for streaming detect | ~3 | Advanced |

‎docs/wiki/Home.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# CodeRoot.ai — Home
22

33
Description: CodeRoot.ai repository
4-
Version: 0.0.0
4+
version: 0.5.0
55

66
What it is
77

@@ -11,7 +11,7 @@ Start here
1111

1212
- Read Installation.md for how to get the commercial extension
1313
- See Commands.md for common actions
14-
- Review PCM_1.1.7_Summary.md for the on-disk format we emit
14+
- Review PCM 1.1.8_Summary.md for the on-disk format we emit
1515

1616
Glossary (short)
1717

‎docs/wiki/Installation.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,7 @@ Get the extension
99

1010
Quick start
1111

12-
1. Open a Git repository in VS Code
13-
2. Run “CodeRoot: Initialize CodeRoot” from the Command Palette
12+
1. Open a Git repository in VS Code 1.90.0 Run “CodeRoot: Initialize CodeRoot” from the Command Palette
1413
3. Run “CodeRoot: Generate Report” to open your first report
1514

1615
Requirements

‎docs/wiki/Provenance Composition Model Snapshot.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
> **Schema version:** v1.1.8
2+
3+
# Provenance Composition Model Snapshot
4+
5+
PCM Snapshots are per-file JSON summaries stored under `.coderoot/v1/snapshots/<relative-path>.pcm.json`. They provide a complete view of file composition without storing source code.
6+
7+
---
8+
9+
## What Snapshots Contain
10+
11+
A snapshot includes:
12+
13+
* **Spans**: Regions of the file (by byte range) with origin, category, and timestamps
14+
* **Summary**: Aggregated counts by origin, category, and subtype
15+
* **Metadata**: File information, encoding, replay checkpoints
16+
17+
---
18+
19+
## Snapshot Structure
20+
21+
### Required Fields
22+
23+
```json
24+
{
25+
"schema_version": "1.1.8",
26+
"file_path": "src/example.txt",
27+
"file_id": "file-abc123",
28+
"updated_at": "2025-10-07T00:00:00Z",
29+
"spans": [...],
30+
"summary": {...},
31+
"meta": {...}
32+
}
33+
```
34+
35+
### Spans
36+
37+
Each span represents a region of the file:
38+
39+
```json
40+
{
41+
"span_id": "s-1",
42+
"range": {
43+
"startByte": 0,
44+
"endByte": 100,
45+
"start": { "line": 0, "column": 0 },
46+
"end": { "line": 5, "column": 10 }
47+
},
48+
"origin": "human",
49+
"category": "human",
50+
"introduced_at": "2025-10-07T00:00:00Z",
51+
"last_modified_at": "2025-10-07T00:00:00Z"
52+
}
53+
```
54+
55+
**Span Fields:**
56+
- `span_id`: Unique identifier for the span
57+
- `range`: Byte range (required) and optional line/column positions
58+
- `origin`: One of `ai`, `human`, `observed`, `untracked`, `external`
59+
- `category`: One of `human`, `automation`, `preexisting`, `out_of_band`
60+
- `introduced_at`: When content was first added
61+
- `last_modified_at`: When content was last modified
62+
63+
### Summary
64+
65+
The summary provides aggregated metrics:
66+
67+
```json
68+
{
69+
"summary": {
70+
"lines_total": 100,
71+
"lines_by_origin": {
72+
"ai": 20,
73+
"human": 70,
74+
"observed": 5,
75+
"external": 5
76+
},
77+
"chars_by_origin": {
78+
"ai": 500,
79+
"human": 2000,
80+
"observed": 100,
81+
"external": 100
82+
},
83+
"lines_by_category": {
84+
"human": 70,
85+
"automation": 20,
86+
"preexisting": 5,
87+
"out_of_band": 5
88+
},
89+
"chars_by_category": {...},
90+
"lines_by_subtype": {...},
91+
"chars_by_subtype": {...},
92+
"touched": 95,
93+
"last_modified_at": "2025-10-07T00:00:00Z"
94+
}
95+
}
96+
```
97+
98+
**Summary Fields:**
99+
- `lines_total`: Total lines in the file
100+
- `lines_by_origin`: Lines broken down by origin (ai, human, observed, external)
101+
- `chars_by_origin`: Characters broken down by origin
102+
- `loc_by_origin`: Lines of code (excluding comments/whitespace) by origin
103+
- `lines_by_category`: Lines broken down by category (human, automation, preexisting, out_of_band)
104+
- `chars_by_category`: Characters broken down by category
105+
- `lines_by_subtype`: Lines broken down by subtype (ai, ai_assisted, tooling, format, etc.)
106+
- `chars_by_subtype`: Characters broken down by subtype
107+
- `touched`: Number of spans that have been modified
108+
- `last_modified_at`: Timestamp of last modification
109+
110+
---
111+
112+
## Origins vs Categories
113+
114+
**Origins** represent the immediate source:
115+
- `human`: Direct human input
116+
- `ai`: AI-generated content
117+
- `observed`: Observed tool output
118+
- `external`: External edits
119+
120+
**Categories** represent the broader classification:
121+
- `human`: Deliberate human work
122+
- `automation`: AI-assisted and trusted automation
123+
- `preexisting`: Baseline content from workspace initialization
124+
- `out_of_band`: External edits needing review
125+
126+
---
127+
128+
## Example Snapshot
129+
130+
```json
131+
{
132+
"schema_version": "1.1.8",
133+
"file_path": "src/example.txt",
134+
"file_id": "file-abc123",
135+
"updated_at": "2025-10-07T00:00:00Z",
136+
"spans": [
137+
{
138+
"span_id": "s-1",
139+
"range": { "startByte": 0, "endByte": 50 },
140+
"origin": "human",
141+
"category": "human",
142+
"introduced_at": "2025-10-07T00:00:00Z",
143+
"last_modified_at": "2025-10-07T00:00:00Z"
144+
}
145+
],
146+
"summary": {
147+
"lines_total": 10,
148+
"lines_by_origin": { "ai": 0, "human": 10, "observed": 0, "external": 0 },
149+
"chars_by_origin": { "ai": 0, "human": 200, "observed": 0, "external": 0 },
150+
"lines_by_category": { "human": 10, "automation": 0, "preexisting": 0, "out_of_band": 0 },
151+
"touched": 1,
152+
"last_modified_at": "2025-10-07T00:00:00Z"
153+
},
154+
"meta": {
155+
"replay_checkpoint": {
156+
"schema_applied": "1.1.8",
157+
"processed_through_event_id": "e-123",
158+
"processed_through_ts": "2025-10-07T00:00:00Z"
159+
}
160+
}
161+
}
162+
```
163+
164+
---
165+
166+
## Privacy & Safety
167+
168+
Snapshots contain:
169+
- ✅ Byte ranges and positions
170+
- ✅ Line and character counts
171+
- ✅ Content hashes (for verification)
172+
- ✅ Timestamps
173+
- ❌ No source code text
174+
- ❌ No file contents
175+
176+
---
177+
178+
## Version & Compatibility
179+
180+
* **Schema:** v1.1.8
181+
* Snapshots are backward compatible with earlier 1.1.x versions
182+
* This page documents the snapshot format. For event/journal format, see [Provenance Composition Model](Provenance-Composition-Model).

0 commit comments

Comments
 (0)