Cleanup

README.md

@@ -76,7 +76,7 @@ using only Node built-ins.
 
 ## Getting Started
 
-For a shorter walkthrough, see [GETTING_STARTED.md](GETTING_STARTED.md).
+For a shorter walkthrough, see [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md).
 
 Requirements: Node.js 20+ and npm (Electron is the only dependency).
 
@@ -121,17 +121,19 @@ this machine and which packaging tools were unavailable.
 The shipping app makes **zero network calls**. There is no telemetry, no
 update check, no license validation, no cloud sync, no account system, and no
 remote AI. Exports embed no remote fonts or CDN references. See
-[SECURITY.md](SECURITY.md) for the threat model.
+[docs/SECURITY.md](docs/SECURITY.md) for the threat model.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution flow,
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for the full contribution flow,
 including the issue-number requirement for every pull request and the
 clean-room rules.
 
 ## Repository Layout
 
-See [ARCHITECTURE.md](ARCHITECTURE.md) to see the repo layout.
+Project docs live in `docs/`, and prompt handoffs live in `ai_prompts/`.
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the repo layout.
 
 ## License
 

ai_prompts/prompt.md

@@ -614,10 +614,10 @@ Project structure to create:
 
 /README.md
 /LICENSE
-/CONTRIBUTING.md
+/docs/CONTRIBUTING.md
-/CODE_OF_CONDUCT.md
+/docs/CODE_OF_CONDUCT.md
-/SECURITY.md
+/docs/SECURITY.md
-/ARCHITECTURE.md
+/docs/ARCHITECTURE.md
 /.editorconfig
 /.gitattributes
 /.gitignore
@@ -1059,8 +1059,8 @@ Your repository should include these contributor rules from day one:
 - require snapshot fixtures for output changes
 - require changelog entries for user-visible behavior changes
 - use a **Developer Certificate of Origin** sign-off rather than a heavy CLA unless you already expect enterprise legal review
-- include `SECURITY.md` for offline-import and archive-handling issues
+- include `docs/SECURITY.md` for offline-import and archive-handling issues
-- include `ARCHITECTURE.md` so future contributors do not break exporter consistency
+- include `docs/ARCHITECTURE.md` so future contributors do not break exporter consistency
 
 ## Open questions and limitations
 
@@ -1072,4 +1072,4 @@ Official messaging around **Linux support** is also inconsistent: the homepage f
 
 I did not find a documented public **plugin SDK** in the reviewed official materials, only built-in integrations, templates, and customization surfaces. That is why I recommend omitting a plugin system in the clone’s first version. citeturn1view0turn13view0turn38view2
 
-Finally, official docs clearly describe local storage and cloud encryption controls, but they do **not** clearly document local at-rest encryption for the desktop guide store. If you want encrypted local archives, that would be an improvement rather than a strict compatibility requirement. citeturn36view0
+Finally, official docs clearly describe local storage and cloud encryption controls, but they do **not** clearly document local at-rest encryption for the desktop guide store. If you want encrypted local archives, that would be an improvement rather than a strict compatibility requirement. citeturn36view0

ai_prompts/prompt2.md

@@ -1,7 +1,7 @@
 # prompt2.md — Finish StepForge (handoff checklist)
 
 You are finishing a nearly-complete offline desktop app called **StepForge**
-(an Electron + vanilla-JS clone of Folge, see `prompt.md` for the full spec).
+(an Electron + vanilla-JS clone of Folge, see `./prompt.md` for the full spec).
 Work through the unchecked boxes below **in order**, committing after each
 section. Keep every change consistent with the existing code style.
 
@@ -131,7 +131,7 @@ half-done): capture-service fixes and editor additions listed in sections
       (`node scripts/make-sample-guide.js`), commit changes.
 
 ### 8. Docs + final commit
-- [x] Update CHANGELOG.md (### Added: capture menu, block editors,
+- [x] Update `../docs/CHANGELOG.md` (### Added: capture menu, block editors,
       focused-view controls, shortcuts, backups dialog, template
       management, apply-style-across; ### Fixed: window-capture fallback,
       app hides itself during capture).
@@ -139,7 +139,7 @@ half-done): capture-service fixes and editor additions listed in sections
 - [x] Update THIS file: tick every box you completed.
 - [x] Final commit.
 
-## Testing philosophy (from prompt.md — do not violate)
+## Testing philosophy (from ./prompt.md — do not violate)
 
 Tests must exercise real workflows and assert on actual output (parse the
 file that was produced, check the pixels/bytes/structure), NOT grep for

build/agent_audit.md

@@ -1,7 +1,7 @@
 # Environment Audit
 
 Audit performed 2026-06-10 before stack selection, as required by the build
-specification in `prompt.md`.
+specification in `ai_prompts/prompt.md`.
 
 ## Host
 

build/build_report.md

@@ -31,7 +31,7 @@ AppImage require the tools listed above and are skipped on this host.
 ## Offline guarantee
 
 - The shipped app opens no sockets: no telemetry, update checks, license
-  checks, cloud sync, or remote AI. See SECURITY.md.
+  checks, cloud sync, or remote AI. See docs/SECURITY.md.
 - All exporters (PNG/GIF/PDF/DOCX/PPTX/ZIP) are implemented in-repo with
   Node built-ins; Electron is the only third-party dependency
   (dev-time fetch recorded in build/agent_audit.md).

core/locks.js

@@ -8,7 +8,7 @@ const { nowIso, readJsonIfExists } = require('./util');
 /**
  * Advisory sidecar lock files for shared .sfgz guides on network folders.
  * For `guide.sfgz` the lock is `guide.lock-sfgz` next to it. This is a
- * coordination mechanism, not a security boundary (see SECURITY.md).
+ * coordination mechanism, not a security boundary (see docs/SECURITY.md).
  */
 
 const STALE_AFTER_MS = 1000 * 60 * 60 * 8; // 8h: treat crashed holders as stale

examples/sample-data/library/guides/guide-sample-reset-password/guide.json

@@ -13,8 +13,8 @@
     "hideSkippedStepsInExports": true
   },
   "themeOverride": "system",
-  "createdAt": "2026-06-11T02:40:34Z",
+  "createdAt": "2026-06-11T14:16:39Z",
-  "updatedAt": "2026-06-11T02:40:34Z",
+  "updatedAt": "2026-06-11T14:16:39Z",
   "stepsOrder": [
     "step-sample-01-open-users",
     "step-sample-02-enable-policy",

examples/sample-data/library/guides/guide-sample-reset-password/steps/step-sample-01-open-users/step.json

@@ -25,7 +25,7 @@
   "extraImages": [],
   "annotations": [
     {
-      "id": "ann-c74bec0b-6cf4-47ba-b228-73c623637138",
+      "id": "ann-80c0a4c6-8b7a-4ba9-8d38-35be0f890ccb",
       "type": "rect",
       "x": 0.275,
       "y": 0.18,
@@ -41,7 +41,7 @@
       }
     },
     {
-      "id": "ann-2491a459-e852-4c08-bb55-edf78a47a6e9",
+      "id": "ann-403e9d28-8b61-43e8-8a8c-74e35bf8b0ff",
       "type": "number",
       "x": 0.3,
       "y": 0.08,
@@ -60,7 +60,7 @@
   ],
   "textBlocks": [
     {
-      "id": "tb-42639c40-003c-44d7-9cd4-09b4b09ca41f",
+      "id": "tb-9f433853-ccc5-450a-98ed-5dcbde7463ac",
       "position": "after-description",
       "level": "info",
       "title": "Tip",

examples/sample-data/library/guides/guide-sample-reset-password/steps/step-sample-02-enable-policy/step.json

@@ -25,7 +25,7 @@
   "extraImages": [],
   "annotations": [
     {
-      "id": "ann-f6b0cfdd-a867-4811-ad9c-7b31ae7a0476",
+      "id": "ann-d2a29aa5-f083-45b6-8018-bd1e66a878fd",
       "type": "arrow",
       "x": 0.47,
       "y": 0.24,
@@ -41,7 +41,7 @@
       }
     },
     {
-      "id": "ann-3d007177-1e5b-4ed0-8f26-43cd82c7f37d",
+      "id": "ann-d4d4807d-87f4-4b9b-9aac-fe106edafa56",
       "type": "tooltip",
       "x": 0.53,
       "y": 0.13,
@@ -58,7 +58,7 @@
       }
     },
     {
-      "id": "ann-751baf23-eab9-44fc-a811-5c9558de8b38",
+      "id": "ann-a34d3ef1-f227-43ac-a59e-a433dfb7f8d5",
       "type": "number",
       "x": 0.31,
       "y": 0.08,

examples/sample-data/library/guides/guide-sample-reset-password/steps/step-sample-02a-permission-prompt/step.json

@@ -19,7 +19,7 @@
   "annotations": [],
   "textBlocks": [
     {
-      "id": "tb-13a6f26d-fdc1-4aaf-a271-284ed8d9574f",
+      "id": "tb-5ef09593-6f95-475d-b0c6-6144d855bed7",
       "position": "after-description",
       "level": "warn",
       "title": "Access",

examples/sample-data/library/guides/guide-sample-reset-password/steps/step-sample-03-review-confirmation/step.json

@@ -25,7 +25,7 @@
   "extraImages": [],
   "annotations": [
     {
-      "id": "ann-88b33206-1bea-463f-a47d-f2e081311b44",
+      "id": "ann-cab1dba5-f903-47c3-a4ec-efff6f70cc3f",
       "type": "blur",
       "x": 0.49,
       "y": 0.32,
@@ -42,7 +42,7 @@
       "radius": 12
     },
     {
-      "id": "ann-3a833f5a-5be3-44d1-bb61-2546cab82a6b",
+      "id": "ann-f6e54195-1e03-4455-83cf-8ecfafde5993",
       "type": "highlight",
       "x": 0.47,
       "y": 0.24,
@@ -58,7 +58,7 @@
       }
     },
     {
-      "id": "ann-c25a8e0c-b849-4978-881a-c54c3c0ff866",
+      "id": "ann-0c74b069-aad1-4d83-bf96-f902009905d6",
       "type": "number",
       "x": 0.31,
       "y": 0.08,

examples/sample-exports/image-bundle/reset-a-password-in-admin-portal-bundle.json

@@ -3,7 +3,7 @@
   "version": 1,
   "guide": {
     "title": "Reset a password in Admin Portal",
-    "generatedAt": "2026-06-11T02:40:34.633Z"
+    "generatedAt": "2026-06-11T14:16:39.204Z"
   },
   "steps": [
     {

examples/sample-exports/json/reset-a-password-in-admin-portal.json

@@ -1,12 +1,12 @@
 {
   "format": "stepforge-guide",
   "version": 1,
-  "generatedAt": "2026-06-11T02:40:34.633Z",
+  "generatedAt": "2026-06-11T14:16:39.204Z",
   "guide": {
     "title": "Reset a password in Admin Portal",
     "descriptionHtml": "<p>Offline sample guide showing capture, annotations, rich text, and exports.</p>",
-    "createdAt": "2026-06-11T02:40:34Z",
+    "createdAt": "2026-06-11T14:16:39Z",
-    "updatedAt": "2026-06-11T02:40:34Z"
+    "updatedAt": "2026-06-11T14:16:39Z"
   },
   "steps": [
     {
@@ -23,7 +23,7 @@
       },
       "annotations": [
         {
-          "id": "ann-c74bec0b-6cf4-47ba-b228-73c623637138",
+          "id": "ann-80c0a4c6-8b7a-4ba9-8d38-35be0f890ccb",
           "type": "rect",
           "x": 0.275,
           "y": 0.18,
@@ -39,7 +39,7 @@
           }
         },
         {
-          "id": "ann-2491a459-e852-4c08-bb55-edf78a47a6e9",
+          "id": "ann-403e9d28-8b61-43e8-8a8c-74e35bf8b0ff",
           "type": "number",
           "x": 0.3,
           "y": 0.08,
@@ -82,7 +82,7 @@
       },
       "annotations": [
         {
-          "id": "ann-f6b0cfdd-a867-4811-ad9c-7b31ae7a0476",
+          "id": "ann-d2a29aa5-f083-45b6-8018-bd1e66a878fd",
           "type": "arrow",
           "x": 0.47,
           "y": 0.24,
@@ -98,7 +98,7 @@
           }
         },
         {
-          "id": "ann-3d007177-1e5b-4ed0-8f26-43cd82c7f37d",
+          "id": "ann-d4d4807d-87f4-4b9b-9aac-fe106edafa56",
           "type": "tooltip",
           "x": 0.53,
           "y": 0.13,
@@ -115,7 +115,7 @@
           }
         },
         {
-          "id": "ann-751baf23-eab9-44fc-a811-5c9558de8b38",
+          "id": "ann-a34d3ef1-f227-43ac-a59e-a433dfb7f8d5",
           "type": "number",
           "x": 0.31,
           "y": 0.08,
@@ -178,7 +178,7 @@
       },
       "annotations": [
         {
-          "id": "ann-88b33206-1bea-463f-a47d-f2e081311b44",
+          "id": "ann-cab1dba5-f903-47c3-a4ec-efff6f70cc3f",
           "type": "blur",
           "x": 0.49,
           "y": 0.32,
@@ -195,7 +195,7 @@
           "radius": 12
         },
         {
-          "id": "ann-3a833f5a-5be3-44d1-bb61-2546cab82a6b",
+          "id": "ann-f6e54195-1e03-4455-83cf-8ecfafde5993",
           "type": "highlight",
           "x": 0.47,
           "y": 0.24,
@@ -211,7 +211,7 @@
           }
         },
         {
-          "id": "ann-c25a8e0c-b849-4978-881a-c54c3c0ff866",
+          "id": "ann-0c74b069-aad1-4d83-bf96-f902009905d6",
           "type": "number",
           "x": 0.31,
           "y": 0.08,

examples/sample-manifest.json

@@ -1,7 +1,7 @@
 {
   "format": "stepforge-sample-manifest",
   "version": 1,
-  "generatedAt": "2026-06-11T02:40:34.632Z",
+  "generatedAt": "2026-06-11T14:16:39.204Z",
   "guideId": "guide-sample-reset-password",
   "title": "Reset a password in Admin Portal",
   "dataDir": "sample-data",

scripts/build-release.sh

@@ -115,7 +115,7 @@ AppImage require the tools listed above and are skipped on this host.
 ## Offline guarantee
 
 - The shipped app opens no sockets: no telemetry, update checks, license
-  checks, cloud sync, or remote AI. See SECURITY.md.
+  checks, cloud sync, or remote AI. See docs/SECURITY.md.
 - All exporters (PNG/GIF/PDF/DOCX/PPTX/ZIP) are implemented in-repo with
   Node built-ins; Electron is the only third-party dependency
   (dev-time fetch recorded in build/agent_audit.md).

scripts/package-linux.sh

@@ -31,15 +31,11 @@ copy_item core "$APP_DIR/core"
 copy_item exporters "$APP_DIR/exporters"
 copy_item scripts "$APP_DIR/scripts"
 copy_item README.md "$APP_DIR/README.md"
-copy_item ARCHITECTURE.md "$APP_DIR/ARCHITECTURE.md"
-copy_item CHANGELOG.md "$APP_DIR/CHANGELOG.md"
-copy_item CODE_OF_CONDUCT.md "$APP_DIR/CODE_OF_CONDUCT.md"
-copy_item CONTRIBUTING.md "$APP_DIR/CONTRIBUTING.md"
 copy_item LICENSE "$APP_DIR/LICENSE"
-copy_item SECURITY.md "$APP_DIR/SECURITY.md"
+copy_item docs "$APP_DIR/docs"
+copy_item ai_prompts "$APP_DIR/ai_prompts"
 copy_item package.json "$APP_DIR/package.json"
 copy_item package-lock.json "$APP_DIR/package-lock.json"
-copy_item prompt.md "$APP_DIR/prompt.md"
 copy_item examples "$APP_DIR/examples"
 copy_item build/agent_audit.md "$APP_DIR/build/agent_audit.md"
 

tests/checks/test_repo_structure.sh

@@ -9,8 +9,10 @@ set -euo pipefail
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$ROOT_DIR"
 
-for f in README.md LICENSE ARCHITECTURE.md SECURITY.md CONTRIBUTING.md \
+for f in README.md LICENSE package.json \
-         CODE_OF_CONDUCT.md CHANGELOG.md package.json; do
+         docs/ARCHITECTURE.md docs/SECURITY.md docs/CONTRIBUTING.md \
+         docs/CODE_OF_CONDUCT.md docs/CHANGELOG.md docs/GETTING_STARTED.md \
+         ai_prompts/prompt.md ai_prompts/prompt2.md; do
   if [[ ! -s "$f" ]]; then
     echo "Missing or empty required file: $f" >&2
     exit 1