Acoustics, Calibration & Asset Architecture
Structuring Long-Term Project Notes in Portable Plain-Text Markdown
A project archive can survive a move and still lose the trail from a decision to its supporting photograph. Build a folder that keeps that trail intact with six frontmatter fields, sortable dates, relative image links, and a plain-text index. Then copy the folder and spend ten minutes checking three notes, every path they cite, and the recorded decision behind one measurement.
Give each project a root you can move
Start with a folder called lamp-study. Put index.md and README.md at its root, project records in notes/, and photographs or drawings in assets/. Keep the notes one directory below the root. When you put one project on an external drive, you can copy that single folder and bring along the evidence its notes refer to.
Save Markdown as UTF-8 with LF line endings. Use lowercase ASCII letters, digits, and hyphens in filenames, with readable punctuation and accents allowed in the text. Pick exact letter case in every link. If Hinge.jpg and hinge.jpg exist in an old archive, give them distinct names before copying to a case-insensitive drive. Check the incoming references to both before retiring either original path.
Use one note per decision or session. A record called 2026-04-09-fit-check.md should give a returning reader the setup, the observed result, and the next decision. For example, record that a 2.0 mm feeler gauge passed at the hinge and the 2.5 mm gauge bound. Write that as a gap of at least 2.0 mm and less than 2.5 mm under the recorded setup. A photograph can show where you checked. The sentence carries the result when the photograph is unavailable.
Keep six frontmatter fields with written definitions
Place a small block between --- lines at the start of each note. The delimiters are an archive convention. A CommonMark viewer may show the block as ordinary Markdown, so check how importers treat it and keep the essential decision in the body. Quote the values shown here to preserve strings when a YAML importer applies type inference. CommonMark specification and YAML 1.2.2 specification.
---
schema_version: "1"
id: "ls-014"
title: "Hinge fit check"
created: "2026-04-09"
updated: "2026-04-11"
status: "closed"
---
In README.md, define the version as the field contract, the ID as permanent and unique within the archive, and the title as the display label. Assign the next unused number under a unique project prefix and keep the original ID when a note moves. A display title can change on its own. Keeping the old filename saves you from repairing links in every other note that cites the record.
Define status values in the same README. In this archive, open means work remains, closed means the decision has been recorded, and superseded means a later note replaces it. For a superseded record, put the successor ID and a relative link in the first paragraph. Give new fields written definitions and defaults before introducing them. If a future importer drops unfamiliar fields, retain the exported originals until you have compared a few raw files against what it imported.
Record calendar dates and event times separately
Use zero-padded ISO calendar dates such as 2026-04-09 for note creation and the last substantive revision. Keep creation fixed and update the revision date when the result, decision, or evidence changes. A copy operation can change filesystem timestamps, so read these dates from the note itself. Record an earlier bench session in the body if you wrote the note later.
If the order of events matters within one day, record a timestamp with an explicit offset. A test at 2026-04-09T00:15:00+09:00 in Seoul occurred at 2026-04-08T15:15:00Z. Its local session date is April 9 even though its UTC date is April 8. For sorting exact instants as text, normalize to UTC with consistent precision first. Preserve the recorded local time where it explains a shift change or a handoff. RFC 3339 timestamp format.
During intake, check impossible dates such as 2026-02-29 with a calendar-aware check. When you only know the month of an old session, write “April 2026, day unknown” in the body and keep the date you actually created the archive note in created. Assigning the first of the month would give the session a position in the timeline that the evidence cannot support.
Resolve image paths from the note’s directory
Place the fit-check photo in assets/ls-014-hinge-side.jpg and use this image reference in notes/2026-04-09-fit-check.md. Start at notes/, climb one level with ../, then enter assets/. Typing assets/ alone would look for a folder below notes/.

Name the subject and viewpoint in the alt text and keep the reading and units in prose beside the image. If you already have a file called hinge side.jpg, a Markdown destination can use hinge%20side.jpg while the file retains its literal space. A lowercase hyphenated filename is easier to copy by hand. Keep the filename extension aligned with the actual file format when converting an image.
If an app shows the photo but the copied folder has a broken link, inspect the raw destination. The app may have resolved a bare filename by searching the whole project. Test the literal relative path from the copied note’s directory and open the file separately. If it opens there but displays sideways in the new viewer, inspect its orientation metadata. Keep the original when exporting an upright derivative and link to the derivative explicitly.
Maintain an index that opens as text
Use one line per note in index.md. Put the creation date first for predictable sorting, then the ID, link, and a short result that helps you choose the right entry. This link starts from the root index, so its destination begins with notes/.
- 2026-04-09 | ls-014 | [Hinge fit check](notes/2026-04-09-fit-check.md) | 2.0 mm gauge passed
| Reference | Resolves from | Migration consequence |
|---|---|---|
notes/2026-04-09-fit-check.md | Root index directory | Works when the root and notes move together. |
../assets/ls-014-hinge-side.jpg | Note directory | Recheck the parent step if the note moves deeper. |
/assets/ls-014-hinge-side.jpg | Root used by the viewer or host | May point outside a project mounted under a subdirectory. |
[[Hinge fit check]] | Application’s title lookup | Requires an importer that understands wiki links and resolves duplicate titles. |
Reconcile the index by ID. If you count 36 files in notes/ and 36 index rows, still compare both sets of IDs and check for duplicates. Two rows for ls-014 can hide a missing ls-015 even when the counts agree. Confirm that each row’s ID matches the frontmatter at its linked path. With a large archive, the README can specify how to rebuild the index by scanning the notes and sorting by creation date, then by ID.
Run a ten-minute migration drill
Copy the entire root into a differently named parent directory. Open the copy in a plain-text editor and a Markdown viewer with project-specific extensions disabled. Use three notes for the timed drill. Include the oldest note, the newest, and one with a photograph as evidence. If those choices overlap, add another note with a different link pattern.
- Minutes 0–2. Open the copied README and index. Compare the index row count with the note count and record both totals.
- Minutes 2–5. Follow all three index links and confirm that each note’s ID, date, and title agree with its row.
- Minutes 5–8. Resolve every local link in those three notes from the file that contains it. Confirm the exact filename case and open each referenced image from the copied folder.
- Minutes 8–10. Verify one recorded measurement against the named evidence. Write down the time, number of paths checked, and any failed destinations. If the timer expires, record how many paths remain.
A sample result is “3 of 3 notes opened, 6 of 6 local paths resolved, and 1 hinge decision recovered in 8 minutes 40 seconds.” That records what someone could recover during the drill. Before retiring an old workspace, extend the link and ID checks to every note in the copy. After repairing a path, reopen it from the copy and repeat the check on any notes that share the same target.