- HyperFrames documentation now starts with human tasks, gives Studio its own complete manual,
- keeps reusable visuals in Catalog, and moves implementation detail into Developers.
+ The documentation now begins with the situation a person is in: understand the product, make
+ a first video, choose a workflow, edit a project, or recover from a problem.
- Guides
+ Understand
Outcome-first onboarding, workflow selection, media, export, help, and updates.One sendable explanation with a finished video, product loop, examples, and a clear
+ next step.
+ Complete
+
+
+ First video
+ A material-first route from a useful request through creative approval, Studio
+ review, and export.
+ Complete
+
+
+ Workflows
+ An outcome-led chooser plus consistent product, explainer, PR, recut, motion, music,
+ slideshow, and custom-video guides.
Complete
Studio
Verified manual for Storyboard, canvas, layers, timeline, design, animation, assets,
- source, lint, and export.A task-led route for understanding an existing project, making the right kind of
+ change, checking it, and exporting safely.
Complete
- Catalog
+ Recovery
134 generated item pages with agent-first use, concise instructions, and folded
- technical details.
- Complete
-
-
- Developers
- CLI, SDK, packages, schemas, deployment, integrations, and contribution material
- grouped together.
- Complete
-
-
- Header
- Full-width Aspen navigation, logo, search, GitHub, theme toggle, and official
- Playground action.A symptom-first help entrance with small fixes, useful diagnostics, detailed
+ troubleshooting, and human escalation.
Complete
@@ -233,6 +234,14 @@
Rigid internal pipeline guidance presented as a requirement for every user.
Duplicate Catalog titles and technical file tables dominating every item page.
Internal telemetry specifications presented as a normal feedback guide.
+
+ Duplicate Overview, Choose your path, Create with an agent, and Help entrances competing
+ for the same jobs.
+
+
+ Machine-facing Claude Design and Open Design specifications cluttering the human
+ creation journey.
+
diff --git a/research/docs-refactor/JOURNEY-IMPLEMENTATION-MAP.md b/research/docs-refactor/JOURNEY-IMPLEMENTATION-MAP.md
new file mode 100644
index 0000000000..dd643af35b
--- /dev/null
+++ b/research/docs-refactor/JOURNEY-IMPLEMENTATION-MAP.md
@@ -0,0 +1,65 @@
+# Journey implementation map
+
+Status: **Approved and in implementation**
+
+This map prevents individual page edits from drifting away from the approved end-to-end journeys.
+
+## P0 journeys
+
+| Journey | Canonical route | Entry promise | Primary supporting pages | Success state |
+| ----------------------------------- | --------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Understand HyperFrames from zero | `/introduction` | Understand the product in under a minute and see proof | Examples, Quickstart, Studio | Person can explain the agent → project → Studio → result loop and choose a next step |
+| Make a first real video | `/quickstart` | Reach a reviewable result, not merely complete setup | Workflows, Prompting, Studio tour, Export | Video plays in Studio or an exported file exists |
+| Start a specific creation workflow | `/workflows` | Choose by source and outcome without knowing internal skill names | Focused workflow pages, Prompting, Studio | Correct workflow starts with a sufficiently useful request |
+| Review and edit an existing project | `/studio` | Understand the workspace, make the right type of change, and export | Storyboard, Tour, Canvas, Timeline, Animation, Export | Person makes a visible change or exports a version |
+| Recover when something is wrong | `/help` | Start from the symptom and return to the interrupted task | Common questions, general troubleshooting, Studio troubleshooting, Feedback | Person fixes the problem or produces a useful diagnostic |
+
+## Consolidation decisions
+
+- `/guides/create-with-agent` is replaced by `/workflows`.
+- `/guides/choose-your-path` is replaced by `/workflows`.
+- `/guides/help` is replaced by `/help`.
+- Old routes redirect so existing support messages and external links do not break.
+- `/guides` remains a concise task router. It is not the canonical product explanation.
+- `/introduction` remains the one link to send when somebody asks what HyperFrames is.
+
+## Cross-link contract
+
+Every P0 entry route must:
+
+1. confirm the person's situation in the opening screen;
+2. describe the result they will reach;
+3. keep the main path visible before secondary detail;
+4. link forward to the next task;
+5. link to `/help` where the task can fail;
+6. avoid requiring repository or framework architecture knowledge.
+
+Supporting pages should return people to the journey they came from instead of ending in unrelated reference material.
+
+## Visual contract
+
+Available now:
+
+- finished production video on Introduction;
+- product-loop and task-progress diagrams;
+- real Studio workspace imagery;
+- Studio-versus-agent decision diagram;
+- copyable requests based on realistic source material.
+
+Production assets still required:
+
+- 45–60 second “What is HyperFrames?” product-loop video;
+- 75–90 second first-video walkthrough;
+- 60–90 second real Studio tour;
+- 6–12 second task loops for trim, split, text editing, keyframes, Catalog insertion, and export.
+
+Until those assets are produced, existing real videos, screenshots, diagrams, and written equivalents must keep every journey complete.
+
+## Removal rule
+
+A page should be merged, hidden, or removed when it:
+
+- duplicates a canonical entry route;
+- supports no approved journey, real support question, or required reference;
+- introduces internal terminology before the task requires it;
+- ends without helping the person return to a task.
diff --git a/research/docs-refactor/NOTES.md b/research/docs-refactor/NOTES.md
index d0fd23527f..f159637c47 100644
--- a/research/docs-refactor/NOTES.md
+++ b/research/docs-refactor/NOTES.md
@@ -215,6 +215,31 @@ New navigation should be task-shaped:
- Created `USER-JOURNEYS-PROPOSAL.md` as an approval document. It defines seven journeys, recommends five as P0, assigns one canonical starting link to each, and specifies the sequence, success state, visual formats, current gaps, and validation method.
- Public docs should not be restructured again until the journeys are approved.
+### 2026-07-29 — journey implementation approved
+
+- The product owner approved the proposed journey model.
+- Added `JOURNEY-IMPLEMENTATION-MAP.md` as the implementation contract.
+- Began consolidating the P0 entrances around `/introduction`, `/quickstart`, `/workflows`, `/studio`, and `/help`.
+- The established Aspen header, sidebar behavior, right-side table of contents, borders, typography, GitHub control, and agent input treatment remain unchanged.
+
+### 2026-07-29 — journey implementation pass
+
+- Rebuilt the five P0 entrances:
+ - `/introduction` now provides immediate proof, the product loop, human-control guidance, and focused next steps;
+ - `/quickstart` now starts from source material and ends at a played or exported result;
+ - `/workflows` is the canonical outcome-led creation chooser with useful requests;
+ - `/studio` now follows the real review → direct edit or agent revision → check → export journey;
+ - `/help` now starts from visible symptoms and produces a fix or useful diagnostic.
+- Removed the duplicate Choose your path, Create with an agent, and old Help pages. Added redirects for every old route.
+- Added the missing human-facing slideshow workflow, including the current live-deck output and honest MP4 limitation.
+- Standardized the seven existing creation workflow pages with direction approval, review guidance, common problems, and a return to Studio or the workflow chooser.
+- Reworked Catalog around the visual job and Developers around the smallest technical surface.
+- Removed large machine-facing Claude Design and Open Design authoring specifications from the human navigation while preserving their source URLs.
+- Added `VISUAL-PRODUCTION-BRIEFS.md` for the three P0 videos and eight Studio task loops.
+- Updated the visual current-state dashboard around the five approved journeys.
+- Browser-reviewed Introduction, Quickstart, Workflows, Help, Studio, Catalog, and Developers in the local Mintlify preview.
+- `mint validate`, `mint broken-links`, and `git diff --check` pass.
+
## Maintenance issue
- The repo instructions refer to `.agents/skills/hyperframes/SKILL.md`, but that repo-local path is absent in this checkout. The installed current router at `/Users/ularkimsanov/.agents/skills/hyperframes/SKILL.md` was used as the workflow source of truth for this pass.
diff --git a/research/docs-refactor/PLAN.md b/research/docs-refactor/PLAN.md
index e83a02ea25..0bf11910de 100644
--- a/research/docs-refactor/PLAN.md
+++ b/research/docs-refactor/PLAN.md
@@ -2,7 +2,7 @@
## Current approval gate
-Do not begin another public information-architecture or editorial pass until leadership approves the primary user journeys in `USER-JOURNEYS-PROPOSAL.md`.
+Approved by the product owner on 2026-07-29. Public implementation is now in progress.
The approved journeys become the source of truth for:
@@ -13,6 +13,8 @@ The approved journeys become the source of truth for:
- consolidation and removal decisions;
- analytics and usability tests.
+The route-to-journey contract is maintained in `JOURNEY-IMPLEMENTATION-MAP.md`.
+
Status: implementation complete; post-release measurement remains
Started: 2026-07-28
Primary audience: people who want to make, edit, and share videos with HyperFrames
diff --git a/research/docs-refactor/VISUAL-PRODUCTION-BRIEFS.md b/research/docs-refactor/VISUAL-PRODUCTION-BRIEFS.md
new file mode 100644
index 0000000000..2119d38c59
--- /dev/null
+++ b/research/docs-refactor/VISUAL-PRODUCTION-BRIEFS.md
@@ -0,0 +1,137 @@
+# Documentation visual production briefs
+
+Status: **Ready for production**
+
+The written journeys are complete without these assets. These videos and loops are the next improvement: they should reduce explanation time, not decorate pages.
+
+## Shared rules
+
+- Build the videos with HyperFrames so the documentation proves the product through its own output.
+- Use real product states and honest claims.
+- Every video must work muted.
+- Include captions and a written equivalent.
+- Avoid rapid UI montage that looks impressive but teaches nothing.
+- Show the cursor only when its action matters.
+- Keep interface text readable at the final embedded size.
+- End on the next action the page asks the viewer to take.
+
+## P0-A — What is HyperFrames?
+
+**Placement:** `/introduction`, above the first major section
+**Duration:** 45–60 seconds
+**Job:** replace the five-minute verbal product explanation
+
+### Story
+
+1. A person starts with a plain-language request and real source.
+2. The agent confirms the creative direction.
+3. The agent builds a real HyperFrames project.
+4. The project opens in Studio.
+5. A person makes one visible direct edit.
+6. The person asks the agent for one broader revision.
+7. Studio exports the result.
+8. The finished video plays.
+
+### Required message
+
+> An agent creates the first real project. A person reviews and edits it in Studio. HyperFrames exports the result.
+
+### Avoid
+
+- opening with HTML, packages, or rendering architecture;
+- presenting Studio as a separate product;
+- implying that every project begins from a website;
+- showing only a finished montage without the creation loop.
+
+## P0-B — Make your first video
+
+**Placement:** `/quickstart`, after the opening outcome
+**Duration:** 75–90 seconds
+**Job:** show the shortest complete first-use path
+
+### Story
+
+Use one realistic product URL:
+
+1. install the HyperFrames guidance;
+2. send the request;
+3. review the returned brief;
+4. approve it;
+5. show the build at a useful level without waiting through every operation;
+6. open Studio;
+7. watch the complete first version;
+8. make one direct edit;
+9. ask for one broader revision;
+10. export MP4 and play the file.
+
+### On-screen progress
+
+`Request → Brief → Build → Review → Export`
+
+### Avoid
+
+- treating installation as the conclusion;
+- using a fake example domain in the final recording;
+- hiding the creative approval step;
+- cutting before the exported file is visibly played.
+
+## P0-C — Studio in 90 seconds
+
+**Placement:** `/studio`, after the opening description
+**Duration:** 60–90 seconds
+**Job:** orient someone opening an agent-created project
+
+### Story
+
+1. Open an existing project.
+2. Explain Storyboard versus Preview.
+3. Play the complete result.
+4. Select a visible element.
+5. Change its text or design.
+6. Adjust one clip on the timeline.
+7. Show one animation control.
+8. copy one broader feedback message to the agent;
+9. run the project check;
+10. export a named version.
+
+### Required message
+
+> If you can point at the thing, start in Studio. If you need a broader outcome, ask the agent.
+
+## P1 task loops
+
+Each loop should be 6–12 seconds, silent, captioned, and tightly cropped around one task.
+
+| Loop | Placement | Visible success |
+| ---------------------------- | ------------------ | ------------------------------------- |
+| Select and edit text | Canvas | Updated text remains selected |
+| Trim a clip | Timeline | New clip edge and changed playback |
+| Split at the playhead | Timeline | Two clips appear |
+| Add a keyframe | Animation | Diamond appears and movement previews |
+| Add a Catalog item | Assets and Catalog | Item appears in the project |
+| Fix caption timing | Captions | Words align with speech |
+| Save and copy agent feedback | Storyboard | Useful message reaches clipboard |
+| Export MP4 | Export | Finished file appears in the queue |
+
+## Static diagrams
+
+Already implemented in the docs:
+
+- source → agent → project → Studio → result;
+- first-video progress;
+- Studio versus agent decision;
+- developer surface chooser.
+
+Before replacing a diagram with motion, test whether motion makes the relationship easier to understand. Keep the static version as the accessible text equivalent.
+
+## Production approval
+
+Before publishing each video, confirm:
+
+- product controls and names match the current release;
+- source material can be shown publicly;
+- claims are supported;
+- no private paths, tokens, account information, or notifications appear;
+- captions match the final voice or on-screen text;
+- the embedded poster makes sense before playback;
+- the page still works when the video is unavailable.