#21 - [Ch 12] Iterations — CLI auth flow and multi-README browsing - ldraney/mdview

### Type Feature ### Lineage Standalone — scoped from platform-playbook chapter 12 for the full-stack mdview vision. ### Repo `ldraney/mdview` ### User Story As a developer I want the CLI to authenticate and register READMEs with the server So that I can browse all my project docs from my phone ### Context With auth and API tokens in place, the CLI needs to use them. The current CLI reads a local file and starts a server — the new CLI authenticates via API token and registers markdown files with the remote server. Registration crawls intra-repo .md links recursively so one command captures an entire project's docs. A post-commit hook keeps docs current automatically. The web/iOS UI gets a dashboard, file tree per project, and resume-last-read behavior. ### File Targets - `bin/mdview` — add `register` and `config` subcommands, token auth - `app/controllers/readmes_controller.rb` — create (register, list, show) - `app/controllers/projects_controller.rb` — create (dashboard, file tree) - `app/models/readme.rb` — create (user_id, project_name, path, content, last_synced_at) - `app/models/project.rb` — create (user_id, name, root_readme_path) - `app/views/projects/` — dashboard (home) and file tree views - `app/views/readmes/` — reader view - `db/migrate/` — readmes and projects tables - `lib/mdview/crawler.rb` — intra-repo .md link crawl logic - `lib/mdview/link_validator.rb` — broken link detection + cross-repo warnings Files the agent should NOT touch: - Deployment overlays — no infra changes in iteration phase ### Feature Flag none ### Acceptance Criteria #### Registration crawl - [ ] `mdview register ~/project/README.md` crawls all intra-repo .md links recursively - [ ] All reachable .md files within the repo are pushed to the server in one registration - [ ] Re-running `mdview register` updates existing content (idempotent) #### Link validation - [ ] Broken intra-repo links are flagged at registration time (file referenced but doesn't exist) - [ ] Cross-repo links to unregistered repos produce a warning (not an error) - [ ] Cross-repo links to registered repos resolve correctly in the reader #### Post-commit hook - [ ] `mdview register "$(git rev-parse --show-toplevel)/README.md"` works as a post-commit hook - [ ] Docs update automatically on every commit with the hook installed #### CLI auth - [ ] `mdview config --token <token>` stores the API token locally - [ ] CLI authenticates with `Authorization: Bearer <token>` on all register requests - [ ] Clear error message when token is missing or invalid #### Web/iOS UI - [ ] Home dashboard lists all registered projects with file counts - [ ] Project file tree screen shows all registered .md files per project - [ ] Reader renders markdown with mermaid support and gruvbox theme - [ ] App opens to the last page the user was reading (resume behavior) - [ ] Home button navigates back to dashboard from any screen - [ ] Back button navigates to previous .md file #### Gate - [ ] At least 10 PRs merged covering features, fixes, and polish ### Test Expectations - [ ] Unit test: crawler discovers all linked .md files within a repo - [ ] Unit test: link validator detects broken intra-repo links - [ ] Unit test: link validator warns on unregistered cross-repo links - [ ] Integration test: CLI registration flow end-to-end - [ ] Integration test: dashboard shows user's projects only - [ ] Integration test: resume behavior stores and restores last read position - Run command: `bundle exec rspec` ### Constraints - Keep the gruvbox dark theme for all new views - Relative .md link rewriting must work for registered READMEs - Crawler must not follow links outside the repo root (no escaping via `../../../`) - See `docs/ui-ux.md` for screen mockups and flow diagrams ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-mdview` — project this affects

ldraney commented

2026-08-01 19:03:46 +00:00

Owner

Type

Feature

Lineage

Standalone — scoped from platform-playbook chapter 12 for the full-stack mdview vision.

Repo

ldraney/mdview

User Story

As a developer
I want the CLI to authenticate and register READMEs with the server
So that I can browse all my project docs from my phone

Context

With auth and API tokens in place, the CLI needs to use them. The current CLI reads a local file and starts a server — the new CLI authenticates via API token and registers markdown files with the remote server. Registration crawls intra-repo .md links recursively so one command captures an entire project's docs. A post-commit hook keeps docs current automatically. The web/iOS UI gets a dashboard, file tree per project, and resume-last-read behavior.

File Targets

bin/mdview — add register and config subcommands, token auth
app/controllers/readmes_controller.rb — create (register, list, show)
app/controllers/projects_controller.rb — create (dashboard, file tree)
app/models/readme.rb — create (user_id, project_name, path, content, last_synced_at)
app/models/project.rb — create (user_id, name, root_readme_path)
app/views/projects/ — dashboard (home) and file tree views
app/views/readmes/ — reader view
db/migrate/ — readmes and projects tables
lib/mdview/crawler.rb — intra-repo .md link crawl logic
lib/mdview/link_validator.rb — broken link detection + cross-repo warnings

Files the agent should NOT touch:

Deployment overlays — no infra changes in iteration phase

Feature Flag

none

Acceptance Criteria

Registration crawl

mdview register ~/project/README.md crawls all intra-repo .md links recursively
All reachable .md files within the repo are pushed to the server in one registration
Re-running mdview register updates existing content (idempotent)

Link validation

Broken intra-repo links are flagged at registration time (file referenced but doesn't exist)
Cross-repo links to unregistered repos produce a warning (not an error)
Cross-repo links to registered repos resolve correctly in the reader

Post-commit hook

mdview register "$(git rev-parse --show-toplevel)/README.md" works as a post-commit hook
Docs update automatically on every commit with the hook installed

CLI auth

mdview config --token <token> stores the API token locally
CLI authenticates with Authorization: Bearer <token> on all register requests
Clear error message when token is missing or invalid

Web/iOS UI

Home dashboard lists all registered projects with file counts
Project file tree screen shows all registered .md files per project
Reader renders markdown with mermaid support and gruvbox theme
App opens to the last page the user was reading (resume behavior)
Home button navigates back to dashboard from any screen
Back button navigates to previous .md file

Gate

At least 10 PRs merged covering features, fixes, and polish

Test Expectations

Unit test: crawler discovers all linked .md files within a repo
Unit test: link validator detects broken intra-repo links
Unit test: link validator warns on unregistered cross-repo links
Integration test: CLI registration flow end-to-end
Integration test: dashboard shows user's projects only
Integration test: resume behavior stores and restores last read position
Run command: bundle exec rspec

Constraints

Keep the gruvbox dark theme for all new views
Relative .md link rewriting must work for registered READMEs
Crawler must not follow links outside the repo root (no escaping via ../../../)
See docs/ui-ux.md for screen mockups and flow diagrams

Checklist

PR opened
Tests pass
No unrelated changes

project-mdview — project this affects

ldraney added the

phase:4

label

2026-08-01 20:21:18 +00:00

Rows
Columns

[Ch 12] Iterations — CLI auth flow and multi-README browsing #21