Update README and add UI/UX doc for full-stack vision

ldraney commented

2026-08-01 19:39:07 +00:00

Owner

Summary

Rewrite README from local-only CLI description to full-stack vision (register, server, auth, mobile)
Add docs/ui-ux.md with 5 screens, 3 flows, and design decisions
Define registration crawl behavior and link validation rules

Changes

README.md: rewritten — now describes register/server/mobile flow, keeps local mode as current behavior, new architecture diagram with CLI/server/client layers, expanded stack table
docs/ui-ux.md: new — login, home dashboard, reader, project file tree, settings screens; first-time setup flow, ongoing usage flow, registration crawl flow; design decisions (resume behavior, link validation, gruvbox theme)

Test Plan

Verify all doc links in README resolve to existing files
Review UI/UX screens match the full-stack vision
Confirm local mode usage is still documented

Review Checklist

Passed automated review-fix loop
No secrets committed
No unnecessary file changes
Commit messages are descriptive
Feature flag needed? No — documentation only

project-mdview — the project this work belongs to
Closes #14

## Summary - Rewrite README from local-only CLI description to full-stack vision (register, server, auth, mobile) - Add docs/ui-ux.md with 5 screens, 3 flows, and design decisions - Define registration crawl behavior and link validation rules ## Changes - `README.md`: rewritten — now describes register/server/mobile flow, keeps local mode as current behavior, new architecture diagram with CLI/server/client layers, expanded stack table - `docs/ui-ux.md`: new — login, home dashboard, reader, project file tree, settings screens; first-time setup flow, ongoing usage flow, registration crawl flow; design decisions (resume behavior, link validation, gruvbox theme) ## Test Plan - [ ] Verify all doc links in README resolve to existing files - [ ] Review UI/UX screens match the full-stack vision - [ ] Confirm local mode usage is still documented ## Review Checklist - [ ] Passed automated review-fix loop - [ ] No secrets committed - [ ] No unnecessary file changes - [ ] Commit messages are descriptive - [ ] Feature flag needed? No — documentation only ## Related Notes - `project-mdview` — the project this work belongs to - Closes #14

ldraney added 1 commit

2026-08-01 19:39:07 +00:00

Update README and add UI/UX doc for full-stack vision

CI / scan_ruby (pull_request) Waiting to run

Details

CI / scan_js (pull_request) Waiting to run

Details

CI / lint (pull_request) Waiting to run

Details

18348bfe7d

README now describes the register/server/mobile flow instead of
local-only CLI usage. New docs/ui-ux.md defines five screens (login,
home, reader, file tree, settings), registration crawl behavior, and
link validation rules.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ldraney commented

2026-08-01 19:42:32 +00:00

Author

Owner

PR #27 Review

DOMAIN REVIEW

Tech stack: Documentation (Markdown, Mermaid diagrams). No code changes.

Files changed: README.md (rewritten), docs/ui-ux.md (new). 289 additions, 28 deletions across 2 files.

Link integrity: All doc links in the README resolve to files that exist in the repo or are added by this PR:

docs/ui-ux.md -- added in this PR
docs/filetree.md -- exists
docs/dependencies.md -- exists
docs/request-lifecycle.md -- exists

Mermaid diagrams: Four diagrams total (two in README, three in docs/ui-ux.md). All syntactically valid. One logical concern noted below in NITS.

Content quality: The UI/UX doc is thorough -- five screens with ASCII mockups, three flows with mermaid diagrams, and three design decision rationales. The README restructure clearly separates CLI, registration, auth, and mobile sections.

BLOCKERS

None. This is a documentation-only PR. No code, no security surface, no test coverage requirements.

NITS

Wrong issue reference. PR body says "Closes #14" but issue #14 is "Browser shows stale content after re-running mdview with different file" -- a bug that was already fixed by PR #15 and is already closed. This PR (docs/vision updates) has no relationship to that issue. The Closes #14 should either be removed or corrected to reference the actual parent issue for this docs work.
Branch naming vs SOP. Branch docs/full-stack-vision does not follow the {issue-number}-description convention. This is partly a consequence of nit #1 -- the issue reference itself is wrong, so the branch cannot follow an issue it does not belong to.
Future functionality reads as current. The README opens with "Browse your project docs from your phone" and the "How It Works" section describes register/push/browse as a working flow. The disclaimer appears later in the "Local mode (current)" subsection: "This is how mdview works today -- the register/server flow is the full-stack vision." Consider either (a) leading with "mdview is a local markdown viewer growing into a full-stack doc browser" or (b) adding a "Status" callout near the top so readers understand the vision/current split before reading the register flow.
Registration crawl diagram logic. In docs/ui-ux.md, node E ("Add to registration set") connects to both G ("Recurse: crawl linked file") and J ("Push all files to server") simultaneously. Logically, recursion should exhaust before pushing. A clearer flow would be: E -> G (loop back to C), then a separate termination edge from the recursion to J.
Email in mockup. The Settings screen in docs/ui-ux.md uses devopsphilosopher@gmail.com. Consider user@example.com to decouple the docs from a specific real address.

SOP COMPLIANCE

Branch named after issue number -- docs/full-stack-vision does not follow {N}-description convention
PR body follows template -- Summary, Changes, Test Plan, Review Checklist, Related Notes all present
No secrets committed -- no API keys, tokens, or credentials
No unnecessary file changes -- 2 files, both directly relevant
Closes correct issue -- references #14 (stale render bug, already closed), not the actual parent issue for this work

PROCESS OBSERVATIONS

Missing parent issue. No open issue in the mdview repo tracks "update README and add UI/UX doc for full-stack vision." The docs work appears to have been done without a planning issue. If this is intentional (ad-hoc docs improvement), note that in the PR body. If a parent issue should exist, create one.
Deployment frequency: Docs-only PRs carry near-zero change failure risk. Quick merge keeps documentation current with the project's evolving vision.
Documentation gap: The README now describes a full-stack architecture (CLI + server + mobile) but the repo has no tracking mechanism for which parts are implemented vs planned. Consider a status table or roadmap section as the implementation progresses.

VERDICT: APPROVED

Clean documentation PR. No blockers. The issue reference mismatch (nit #1) and branch naming (nit #2) are process hygiene items worth fixing but do not block merge. The content itself is well-structured, links are valid, and the vision is clearly articulated.

## PR #27 Review ### DOMAIN REVIEW **Tech stack:** Documentation (Markdown, Mermaid diagrams). No code changes. **Files changed:** `README.md` (rewritten), `docs/ui-ux.md` (new). 289 additions, 28 deletions across 2 files. **Link integrity:** All doc links in the README resolve to files that exist in the repo or are added by this PR: - `docs/ui-ux.md` -- added in this PR - `docs/filetree.md` -- exists - `docs/dependencies.md` -- exists - `docs/request-lifecycle.md` -- exists **Mermaid diagrams:** Four diagrams total (two in README, three in `docs/ui-ux.md`). All syntactically valid. One logical concern noted below in NITS. **Content quality:** The UI/UX doc is thorough -- five screens with ASCII mockups, three flows with mermaid diagrams, and three design decision rationales. The README restructure clearly separates CLI, registration, auth, and mobile sections. ### BLOCKERS None. This is a documentation-only PR. No code, no security surface, no test coverage requirements. ### NITS 1. **Wrong issue reference.** PR body says "Closes #14" but issue #14 is "Browser shows stale content after re-running mdview with different file" -- a bug that was already fixed by PR #15 and is already closed. This PR (docs/vision updates) has no relationship to that issue. The `Closes #14` should either be removed or corrected to reference the actual parent issue for this docs work. 2. **Branch naming vs SOP.** Branch `docs/full-stack-vision` does not follow the `{issue-number}-description` convention. This is partly a consequence of nit #1 -- the issue reference itself is wrong, so the branch cannot follow an issue it does not belong to. 3. **Future functionality reads as current.** The README opens with "Browse your project docs from your phone" and the "How It Works" section describes register/push/browse as a working flow. The disclaimer appears later in the "Local mode (current)" subsection: "This is how mdview works today -- the register/server flow is the full-stack vision." Consider either (a) leading with "mdview is a local markdown viewer growing into a full-stack doc browser" or (b) adding a "Status" callout near the top so readers understand the vision/current split before reading the register flow. 4. **Registration crawl diagram logic.** In `docs/ui-ux.md`, node E ("Add to registration set") connects to both G ("Recurse: crawl linked file") and J ("Push all files to server") simultaneously. Logically, recursion should exhaust before pushing. A clearer flow would be: E -> G (loop back to C), then a separate termination edge from the recursion to J. 5. **Email in mockup.** The Settings screen in `docs/ui-ux.md` uses `devopsphilosopher@gmail.com`. Consider `user@example.com` to decouple the docs from a specific real address. ### SOP COMPLIANCE - [ ] Branch named after issue number -- `docs/full-stack-vision` does not follow `{N}-description` convention - [x] PR body follows template -- Summary, Changes, Test Plan, Review Checklist, Related Notes all present - [x] No secrets committed -- no API keys, tokens, or credentials - [x] No unnecessary file changes -- 2 files, both directly relevant - [ ] Closes correct issue -- references #14 (stale render bug, already closed), not the actual parent issue for this work ### PROCESS OBSERVATIONS - **Missing parent issue.** No open issue in the mdview repo tracks "update README and add UI/UX doc for full-stack vision." The docs work appears to have been done without a planning issue. If this is intentional (ad-hoc docs improvement), note that in the PR body. If a parent issue should exist, create one. - **Deployment frequency:** Docs-only PRs carry near-zero change failure risk. Quick merge keeps documentation current with the project's evolving vision. - **Documentation gap:** The README now describes a full-stack architecture (CLI + server + mobile) but the repo has no tracking mechanism for which parts are implemented vs planned. Consider a status table or roadmap section as the implementation progresses. ### VERDICT: APPROVED Clean documentation PR. No blockers. The issue reference mismatch (nit #1) and branch naming (nit #2) are process hygiene items worth fixing but do not block merge. The content itself is well-structured, links are valid, and the vision is clearly articulated.

ldraney added 1 commit

2026-08-01 19:44:23 +00:00

Address review nits: status callout, email, crawl diagram

CI / scan_ruby (pull_request) Waiting to run

Details

CI / scan_js (pull_request) Waiting to run

Details

CI / lint (pull_request) Waiting to run

Details

6048dfa8ea

- Add status callout at top of README clarifying vision vs current state
- Replace real email with user@example.com in Settings mockup
- Fix crawl diagram: recursion exhausts before push step

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>