Build Craft

The build, in order

1. 1

   Local foundation and data contract

   hideshow

   Create the runnable local foundation for a local document library with portable Markdown and safe backlinks, including the real schema and acceptance fixture.

   1. 1.1Create and start the local application

      Run the venv command first, then stop and activate it before running the remaining commands. Use your OS instructions: Windows .venv\Scripts\activate.bat in cmd, or .venv\Scripts\Activate.ps1 in PowerShell; macOS/Linux source .venv/bin/activate. Then install the listed packages. Create app.py exposing app, load .env with python-dotenv, and add a /healthz route. Freeze tested dependency versions to requirements.txt. Create .env manually from .env.example; replace SECRET_KEY before launch.

      Files app.pyrequirements.txt.env.example.gitignore

      terminalcopy

      python -m venv .venv
      python -m pip install Flask Flask-WTF python-dotenv waitress tzdata markdown bleach
      python -m pip freeze > requirements.txt
      python -m flask --app app run --host 127.0.0.1

   2. 1.2Implement storage and seed the named fixture

      For database-backed state create schema.sql and db.py using this model: notes(id,title,path,content_hash); links(source_id,target_id); tags(note_id,tag); revisions(id,note_id,hash,snapshot_path); Markdown files in a user-selected vault are canonical. Add the auxiliary relationships explicitly used in later phases; use stable ids, foreign keys, parameterized values and transactions. For canonical files use atomic replacement and hashes instead. Implement python manage.py init and python manage.py seed to create only synthetic data: Two Markdown notes linked by stable note ids, an image and an externally edited file. Re-running init must not erase data.

      Files schema.sqldb.pymanage.pyfixtures/README.md

      terminalcopy

      python manage.py init
      python manage.py seed

   3. 1.3Protect the local request boundary

      Install Flask-WTF CSRF protection for forms and same-origin fetches, validate Host and Origin against SITE_URL, bound inputs and escape output. Deliberately public intake endpoints get bounded validation and rate limits; signed provider webhooks use signature checks instead of browser CSRF tokens. All other admin routes stay local until product authentication exists. When a later phase tests viewer/member permissions, implement the users, hashed passwords, expiring server sessions and role checks in this foundation first; product mode must never use a fabricated identity from request input. Add error, empty, keyboard-focus and retry states now.

      Files app.pytemplates/base.htmltest/test_foundation.py

   done when · tick each as it passes

   • The documented start command serves /healthz and the initial screen at http://127.0.0.1:5000.
   • Restarting preserves the seeded records or canonical files; running init again deletes nothing.
   • A cross-origin state-changing request to an admin route is refused.

   watch out

   • The Flask development server is for local development only. Loopback binding alone does not replace CSRF and origin validation.

   next phase
2. 2

   File-backed writing

   hideshow

   File-backed writing for Craft: Implement a plain Markdown editor that saves via temporary file and atomic replace; index titles and hashes in SQLite.

   1. 2.1Implement a plain Markdown editor that saves via temporary file and atomic replace; index titles and hashes in SQLite.

      Implement a plain Markdown editor that saves via temporary file and atomic replace; index titles and hashes in SQLite.

      Files features/file_backed_writing.pytemplates/file_backed_writing.html

   2. 2.2Restrict all paths to the vault; compare hashes before saving and offer reload or save-as on external edits.

      Restrict all paths to the vault; compare hashes before saving and offer reload or save-as on external edits.

      Files features/file_backed_writing.py

   3. 2.3Exercise the acceptance fixture

      Use Two Markdown notes linked by stable note ids, an image and an externally edited file. Check: Editing a file outside the app triggers a conflict instead of overwriting it. Then check: A note named ../../outside cannot write outside the vault. Add a focused regression for the failure case under test/ using a temporary database or folder and fake external services; also perform the visible workflow in a browser.

      Files test/test_file_backed_writing.py

      terminalcopy

      python -m unittest discover -s test

   done when · tick each as it passes

   • Editing a file outside the app triggers a conflict instead of overwriting it.
   • A note named ../../outside cannot write outside the vault.

   watch out

   • SQLite is a rebuildable index; it must not become a second competing source of document truth.

   next phase
3. 3

   Links and navigation

   hideshow

   Links and navigation for Craft: Resolve note links by stable ids, render backlinks and provide keyboard search over titles and text.

   1. 3.1Resolve note links by stable ids, render backlinks and provide keyboard search over titles and text.

      Resolve note links by stable ids, render backlinks and provide keyboard search over titles and text.

      Files features/links_and_navigation.pytemplates/links_and_navigation.html

   2. 3.2Implement rename as a title/path change that preserves id; show unresolved links rather than silently creating notes.

      Implement rename as a title/path change that preserves id; show unresolved links rather than silently creating notes.

      Files features/links_and_navigation.py

   3. 3.3Exercise the acceptance fixture

      Use Two Markdown notes linked by stable note ids, an image and an externally edited file. Check: Renaming a linked note preserves its incoming link and backlink. Then check: Searching a unique phrase finds the right note after an index rebuild. Add a focused regression for the failure case under test/ using a temporary database or folder and fake external services; also perform the visible workflow in a browser.

      Files test/test_links_and_navigation.py

      terminalcopy

      python -m unittest discover -s test

   done when · tick each as it passes

   • Renaming a linked note preserves its incoming link and backlink.
   • Searching a unique phrase finds the right note after an index rebuild.

   watch out

   • Filenames alone are brittle identities for linked documents.

   next phase
4. 4

   Portable presentation

   hideshow

   Portable presentation for Craft: Render sanitized Markdown previews with local attachments and readable print styles; disable raw HTML.

   1. 4.1Render sanitized Markdown previews with local attachments and readable print styles; disable raw HTML.

      Render sanitized Markdown previews with local attachments and readable print styles; disable raw HTML.

      Files features/portable_presentation.pytemplates/portable_presentation.html

   2. 4.2Export the entire vault with an id/path manifest and implement import preview plus index rebuild.

      Export the entire vault with an id/path manifest and implement import preview plus index rebuild.

      Files features/portable_presentation.py

   3. 4.3Exercise the acceptance fixture

      Use Two Markdown notes linked by stable note ids, an image and an externally edited file. Check: Export and reimport preserve both notes, the image and links. Then check: An embedded script in Markdown cannot execute in preview or print. Add a focused regression for the failure case under test/ using a temporary database or folder and fake external services; also perform the visible workflow in a browser.

      Files test/test_portable_presentation.py

      terminalcopy

      python -m unittest discover -s test

   done when · tick each as it passes

   • Export and reimport preserve both notes, the image and links.
   • An embedded script in Markdown cannot execute in preview or print.

   watch out

   • This is a local web editor; native Craft layout fidelity and proprietary sync are excluded.

   next phase
5. 5

   Portable delivery and clean-start proof

   hideshow

   Finish the Craft replacement with a documented first-run path and a recoverable export.

   1. 5.1Write the user-facing runbook

      Document prerequisites, every configuration variable, data locations and the three domain workflows: File-backed writing; Links and navigation; Portable presentation. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them.

      Files README.md.env.example

   2. 5.2Create and rehearse a recoverable backup

      Pause edits and snapshot the whole Markdown vault including attachments and revision snapshots; the SQLite search index is rebuildable. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: Two Markdown notes linked by stable note ids, an image and an externally edited file. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy.

      Files OPERATIONS.mdscripts/backup.py

   3. 5.3Reproduce the first-run experience

      Use a new folder and only README instructions to reach the fixture outcome. Install from requirements.txt, initialize storage, run the tests and exercise the UI at 375px and 1280px; use keyboard-only controls and inspect browser errors. Record exactly what passed; do not mark unrun checks complete.

      Files README.mdverification.md

      terminalcopy

      python -m pip install -r requirements.txt
      python -m unittest discover -s test

   done when · tick each as it passes

   • A new folder reaches the documented fixture outcome using only README instructions.
   • A backup restored in isolation preserves the proof data and can be opened.

   watch out

   • Export without an import or restore rehearsal is not verified portability.