Case Study
trail.venturanomadica.com
The Trail Framework website. Built end-to-end using Trail.
# Intent — trail-site: Brushy Case Study
Owner: James
Last Updated: 2026-03-25
---
## Purpose
The trail-site has a case studies section that currently lists all case studies
as "Coming Soon." Brushy is the first case study ready to publish. This intent
builds the Brushy case study page and updates the case studies landing page to
link to it. The Brushy case study demonstrates Trail's predecessor framework
(ADF) and serves as a concrete proof point for the Trail Framework public launch.
---
## Constraints
- **Technical:** PHP, HTML, CSS, vanilla JS only. No frameworks, no build tools.
- **Syntax highlighting:** highlight.js is used for colorized code block rendering.
It is already in use on the site.
- **Style:** The site stylesheet (`style.css`) and brand guidelines govern all
visual decisions. The style guide is at `trail/meta/files/trail-style-guide.html`.
- **Content:** All page copy is provided. Do not invent or alter copy.
- **ADF file names:** Brushy was built with ADF, the precursor to Trail. File
naming differs from current Trail conventions. The mapping is:
- `adf/meta/ai-instructions.md` = equivalent to `global-operating-instructions.md`
- `adf/runs/active/.../ai-instructions.md` = equivalent to `operating-instructions.md`
- **Format:** PHP throughout. Consistent with the rest of the site.
---
## Dependencies & Files
**Input files:**
- `trail/meta/files/trail-style-guide.html` — visual design reference
- `trail/meta/files/logos/` — logo variants (full and mark only)
- `case-studies/brushy/adf/` — the ADF artifact files displayed in the file viewer
- `case-studies/brushy/media/` — screenshots and video thumbnail if needed
- `header.php` — shared site header include
- `footer.php` — shared site footer include
- `style.css` — site stylesheet
**External dependencies:**
- YouTube embed: `https://youtube.com/shorts/RhLi_4awZ94?si=TYcFy5iBD5b9-TD_`
- Docs pages for "What's this?" links: `/docs/?page=glossary`, `/docs/?page=changelog`
---
## Scope (In Scope)
- Create `case-studies/brushy/brushy.php` — the Brushy case study page
- Update `case-studies.php` — change the Brushy card from "Coming Soon" to a
live link pointing to `case-studies/brushy/brushy.php`
- All other case study cards remain "Coming Soon" and are not modified
---
## Out of Scope (Non-Goals)
- Any case study other than Brushy
- Individual case study pages for any other product
- Changes to any page outside of `case-studies.php` and `case-studies/brushy/brushy.php`
- Converting or reformatting the ADF files — they are displayed as-is
- App Store links — Brushy has none
- A public Git URL for Brushy — not included at this time
---
## Assumptions
- `brushy.php` does not currently exist. It is being created by this intent.
- `case-studies.php` exists and currently shows Brushy as "Coming Soon."
- highlight.js is already loaded in the site. The Developer does not need to
add a new CDN include if it is already present; if it is not, add it.
- The ADF files in `case-studies/brushy/adf/` are complete and will not change.
- The media files in `case-studies/brushy/media/` are complete and production-ready.
- The Glossary has entries for current Trail file types. For ADF-era file names
(`ai-instructions.md`), the Changelog is the correct "What's this?" destination.
- The two-column layout (sidebar left, main content right) mirrors the Docs section
pattern already established in the site CSS (`.docs-layout`, `.docs-sidebar`, etc.).
---
## Specifics
### Page: `case-studies/brushy/brushy.php`
**Layout**
Two-column layout consistent with the Docs section. Dark sidebar on the left,
main content area on the right.
**Left sidebar**
- Product name at top: "Brushy" — clicking it returns the visitor to the case
study brief (the default main panel view)
- A note indicating this was built with ADF, the precursor to Trail v1.0, with
a link to the Changelog doc
- File tree showing the ADF folder structure:
```
adf/
meta/
ai-instructions.md
intent.md
manager-instructions.md
runs/
active/
run-2026-02-01-20-44-50/
ai-instructions.md
dev-prompt.md
results.md
tasks.md
```
Each file in the tree is clickable. Clicking a file replaces the main panel
with the file viewer. Each file entry has a "What's this?" indicator that links
to the appropriate Glossary or Changelog entry.
**Main panel — default view (brief)**
Stats grid showing:
- Intents: 1
- Planning: 3 hours
- Manager: 15 minutes
- Developer: 30 minutes
- Testing: 30 minutes
Product description (exact copy — do not alter):
> **Brushy — A smart toothbrush app for your dumb toothbrush**
>
> Brushy is a toothbrush timer app for iOS and Android. Brushy is like the app
> that comes with your smart toothbrush, but you don't need an expensive connected
> toothbrush; any old toothbrush will do.
>
> It was built as a proof of concept for ADF, the framework that became Trail.
> The goal was to go from idea to working app as fast as possible with AI doing
> the implementation, while keeping every decision traceable to a written artifact.
YouTube embed (the demo video):
`https://youtube.com/shorts/RhLi_4awZ94?si=TYcFy5iBD5b9-TD_`
Screenshots from `case-studies/brushy/media/`:
- `01-brushy-timer.png`
- `02-brushy-in-progress.png`
- `03-brushy-brushing-complete.png`
- `04-brushy-toothbrush-info.png`
- `05-brushy-calendar.png`
- `06-brushy-settings.png`
Screenshots are portrait orientation (mobile app screens).
**Main panel — file viewer**
Activated when a file is clicked in the sidebar. Replaces the brief entirely.
- A "← Back to Brushy" control returns the visitor to the brief
- File name and full path displayed in the header of the viewer
- A "What's this?" link in the viewer header:
- For `intent.md`, `manager-instructions.md`, `dev-prompt.md`, `tasks.md`,
`results.md` → links to `/docs/?page=glossary`
- For `ai-instructions.md` (both occurrences) → links to `/docs/?page=changelog`
with a label indicating the file name changed in Trail v1.0
- File contents rendered as a colorized code block using highlight.js with
Markdown language. The file is displayed raw — not converted to HTML.
- PHP reads the file from disk. The file path is derived from the sidebar
selection. Directory traversal must be prevented — only files within
`case-studies/brushy/adf/` may be served.
### Page update: `case-studies.php`
The Brushy card currently shows a "Coming Soon" badge and no link. Update it to:
- Remove the "Coming Soon" badge
- Make the card title and/or card itself a link to `case-studies/brushy/brushy.php`
- Add a brief one-line description if the card does not already have one
All other cards remain unchanged.
---
## Deliverables
- `case-studies/brushy/brushy.php` — complete, functional Brushy case study page
- `case-studies.php` — updated Brushy card linking to the case study page
---
## Acceptance Criteria
- `case-studies/brushy/brushy.php` loads without errors
- The two-column layout renders correctly on desktop
- The sidebar displays the correct file tree with all seven files listed
- Clicking each file in the sidebar replaces the main panel with the file's
contents rendered as a colorized Markdown code block
- The "← Back to Brushy" control returns the visitor to the brief view
- The "What's this?" link for `ai-instructions.md` points to the Changelog;
all other files point to the Glossary
- The YouTube video embeds and plays
- All six screenshots are visible
- The stats grid shows the correct values
- Only files within `case-studies/brushy/adf/` can be served by the file reader;
paths outside this directory are rejected
- `case-studies.php` Brushy card links to `case-studies/brushy/brushy.php`
- No other cards on `case-studies.php` are modified
- The page uses `header.php` and `footer.php` includes
- The style guide is applied consistently; no new CSS patterns invented that
conflict with the existing stylesheet
---
## Notes
The case study page establishes the visual and functional pattern for all future
case studies. Future case studies will follow the same layout with their own
folder under `case-studies/` and their own Trail (not ADF) file structure.
The ADF naming difference (ai-instructions.md vs operating-instructions.md) is
a feature of this case study, not a problem. It shows Trail's evolution. The
Changelog link from the "What's this?" indicator is the correct way to handle it.