revamp markdown project files

3 files changed, 104 insertions, 162 deletions

diff --git a/ROADMAP.md b/ROADMAP.md
index c63853a..46af8dd 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,23 +1,5 @@
 # Hutch Roadmap
 
-## Positioning
-
-Hutch is already beyond a minimal v1. The core SourceHut surfaces are present:
-
-- Authentication with PAT flow
-- Git repositories
-- Mercurial repositories
-- Trackers and tickets
-- Builds
-- Sharing
-- Core settings and app metadata
-
-The main risk now is not lack of scope. The main risk is shipping too late with
-an increasingly broad surface area and not enough polish.
-
-This roadmap treats the current app as a real 1.0 candidate and shifts the
-focus from feature expansion to launch readiness.
-
 ## Version 1.0 Goal
 
 Ship a stable SourceHut mobile client with strong support for the most active
@@ -26,10 +8,12 @@ day-to-day workflows:
 - Browse and manage repositories
 - Browse and manage tickets
 - Browse and manage builds
-- Support both git and hg repositories
+- Support both Git and Mercurial repositories
 - Provide dependable sharing and navigation
 
-Version 1.0 does not need to cover every sr.ht service.
+Version 1.0 does not need to cover every SourceHut service.
+
+---
 
 ## Release Strategy
 
@@ -50,25 +34,25 @@ Focus on quality, not new surface area.
   - Build submission
 - Verify build retry and edit/resubmit flows
 - Verify repository sharing links for:
-  - repository
-  - commit
-  - file
+  - Repository
+  - Commit
+  - File
 - Verify sharing links for:
-  - build
-  - tracker
-  - ticket
-  - profile
+  - Build
+  - Tracker
+  - Ticket
+  - Profile
 - Review empty/loading/error states across all main tabs
 - Remove any leftover temporary debug logging
 - Audit device-only issues:
   - Xcode attach quirks
-  - on-device auth/cache behavior
+  - On-device auth/cache behavior
   - WebView rendering performance
 
 #### UI/UX polish checklist
 
 - Tighten wording and error messages across create/edit flows
-- Confirm summary tabs feel consistent across git and hg
+- Confirm summary tabs feel consistent across Git and Mercurial
 - Confirm toolbar actions are visible and non-duplicated
 - Confirm README rendering is smooth on large repositories
 - Confirm forms behave well on iPhone-sized screens
@@ -82,6 +66,8 @@ Focus on quality, not new surface area.
 - Finalize support URL / project URL
 - Decide whether TestFlight comes before public launch
 
+---
+
 ### Phase 2: Version 1.1
 
 Add one compact new service surface after launch.
@@ -99,6 +85,8 @@ Add one compact new service surface after launch.
 - paste.sr.ht is relatively self-contained
 - lists.sr.ht is valuable, but broader in UI and data model scope
 
+---
+
 ### Phase 3: Version 1.2+
 
 Expand only after the v1 core is stable in the wild.
@@ -106,50 +94,5 @@ Expand only after the v1 core is stable in the wild.
 - lists.sr.ht tab
 - paste.sr.ht creation/editing polish
 - pages.sr.ht management
-- broader deep-link/share coverage
-- workflow refinements for builds and tickets
-
-## What Counts As “Done Enough” For 1.0
-
-Hutch is ready for 1.0 when:
-
-- The main flows work reliably on real devices
-- Errors are understandable
-- The app does not feel inconsistent across git/hg/builds/tickets
-- The missing services feel like roadmap items, not broken gaps
-
-That means `lists.sr.ht`, `paste.sr.ht`, and `pages.sr.ht` are not blockers for
-the first release.
-
-## Non-Blockers For 1.0
-
-These should not delay launch:
-
-- Donation page / IAP
-- Broad service parity across all SourceHut products
-- Public repo discovery equivalent to `sr.ht/projects`
-- Advanced creation workflows beyond what the public APIs cleanly support
-
-## Open Product Questions
-
-These are worth deciding before or shortly after launch:
-
-- Should the app be positioned as “SourceHut client” or “SourceHut for git/hg,
-  tickets, and builds” in App Store messaging?
-- Should exact repository lookup live in Repositories search, a dedicated sheet,
-  or both?
-- Should `paste.sr.ht` or `lists.sr.ht` be the first new post-launch tab?
-- Is TestFlight feedback needed before calling the first public build 1.0?
-
-## Recommended Next Step
-
-Do not add another major service right away.
-
-Instead:
-
-1. Run a release-focused polish pass
-2. Build a strict 1.0 checklist from the current app
-3. Ship to TestFlight or release publicly
-4. Use `ROADMAP.md` and `TODO.md` separately:
-   - `ROADMAP.md` for release strategy
-   - `TODO.md` for concrete implementation backlog
+- Broader deep-link/share coverage
+- Workflow refinements for builds and tickets
diff --git a/SECURITY.md b/SECURITY.md
index b7e2b73..1423145 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -2,32 +2,32 @@
 
 ## Supported Versions
 
-This section outlines which versions of the project are currently receiving
-security updates.
+|Version|Supported|
+|-------|---------|
+| 1.x   | ✅ Yes  |
+| < 1.0 | ❌ No   |
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 1.x     | :white_check_mark: |
-| < 1.0   | :x:                |
+---
 
 ## Reporting a Vulnerability
 
-If you discover a vulnerability, please follow the guidelines below to report
-it:
-
-1. **Submission**: Send your vulnerability report to [[email protected]].
-   Please include a detailed description of the issue, steps to reproduce it,
-   and any relevant context.
-
-2. **Response Time**: We aim to acknowledge reports within **3 business days**.
-   You will receive updates on the status of your report throughout the process.
-
-3. **Acceptance Criteria**: If the vulnerability is confirmed, we will provide
-   you with an estimated timeline for resolution and keep you informed of any
-   updates until the issue is resolved.
-
-4. **Declined Reports**: If a reported vulnerability is deemed invalid or out of
-   scope, we will notify you of our decision and provide reasoning for the
-   decline.
-
-Thank you for helping us improve the security of our project!
+If you discover a security vulnerability, **do not open a public issue**.
+Instead:
+
+1. **Email** your report to [[email protected]](mailto:[email protected]).
+  Include:
+  - A detailed description of the vulnerability
+  - Steps to reproduce
+  - Any relevant context (e.g., affected versions, environment)
+2. **Response Time**: We will acknowledge your report within **3 business days**
+  and keep you updated on the progress.
+3. **Resolution**: If confirmed, we will:
+  - Provide an estimated timeline for a fix
+  - Work with you to verify the resolution
+  - Credit you for the discovery (if you wish)
+4. **Declined Reports**: If the report is invalid or out of scope, we will
+  explain why and close the issue.
+
+---
+
+**Thank you for helping improve the security of our project!**
diff --git a/TODO.md b/TODO.md
index 946d5f1..65a7617 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,68 +1,67 @@
-# Hutch TODO
-
-## Claude Code, Codex, & Mistral Prompting Notes
-
-- **Always start a new session with the project context block** (see
-  hutch-ios-prompts.md prompt 0) so the agent knows the API conventions.
-- **Keep prompts short and specific.** Long prompts waste context. One bug or
-  feature per prompt. Paste console output and error messages directly instead
-  of describing them.
-- **When a fix fails twice, ask the agent to print raw state first** (raw API
-  response, current file contents, exact variable values) before attempting
-  another fix. Blind retries consume context without progress.
-- **Never paste full file contents into the prompt.** Ask the agent to read
-  the file itself using its file tools.
-- **Batch only tightly related changes.** Unrelated changes in one prompt
-  increase the chance of partial failure and wasted context on rollback.
-
-## Features
-
-- **Exact repository lookup**: Since public repository discovery/search is not
-  exposed in the public sr.ht API, add a manual `~owner/repo` lookup flow that
-  can open git.sr.ht or hg.sr.ht repositories directly.
-
-- **paste.sr.ht tab**: Paste support. Endpoint:
-  https://paste.sr.ht/graphql. Show the authenticated user's pastes, allow
-  viewing individual pastes, and support creating new pastes. Required scope:
-  PASTES:RO for browsing, PASTES:RW for creation/editing.
-
-- **lists.sr.ht tab**: Mailing list support. Endpoint:
-  https://lists.sr.ht/graphql. Show the authenticated user's mailing lists,
-  allow browsing email threads, and display individual emails as plain text.
-  Required scope: LISTS:RO.
-
-- **pages.sr.ht tab**: Site management support. Endpoint:
-  https://pages.sr.ht/graphql. Show the authenticated user's published sites,
-  site metadata, publishing status, and access control where supported. This is
-  for managing Pages sites, not browsing public project discovery.
-
-- **Donation page / IAP**: Add a donation/support page once the App Store /
-  StoreKit setup is ready.
+# TODO
 
-## Out of Scope
+---
+
+## TODO List
+
+### Core Functionality
+
+- Implement manual `~owner/repo` lookup flow for opening git.sr.ht or hg.sr.ht
+  repositories directly
+
+---
+
+### paste.sr.ht
+
+- **Endpoint:** [https://paste.sr.ht/graphql](https://paste.sr.ht/graphql)
+- **Scope:** `PASTES:RO` (browsing), `PASTES:RW` (creation/editing)
+
+**Tasks:**
+
+- Show the authenticated user’s pastes
+- Allow viewing individual pastes
+- Support creating new pastes
+
+---
 
-- **Universal links** (e.g. tapping a git.sr.ht URL in Safari opens Hutch):
-  Requires Sourcehut to host an apple-app-site-association file on their
-  servers. This is outside our control. The hutch:// custom URL scheme works as
-  a fallback for links we generate ourselves.
+### lists.sr.ht
 
-- **Push notifications for builds and tickets**: The sr.ht API only supports
-  server-side webhooks (HTTP POST to a URL you control). Delivering push
-  notifications to iOS would require a backend relay server to receive webhooks
-  and forward them via APNs. Out of scope for a personal app with no backend.
+- **Endpoint:** [https://lists.sr.ht/graphql](https://lists.sr.ht/graphql)
+- **Scope:** `LISTS:RO`
 
-- **Contribution activity / GitHub-style heatmap**: No aggregate contributions
-  endpoint exists in the sr.ht GraphQL API. Computing this would require
-  paginating every repository's full commit log and filtering by author --
-  extremely slow and not practical.
+**Tasks:**
 
-- **Explore / search (hub.sr.ht)**: The public hub.sr.ht GraphQL API does not
-  expose repository discovery/search or a projects feed comparable to
-  https://sr.ht/projects.
+- Show the authenticated user’s mailing lists
+- Allow browsing email threads
+- Display individual emails as plain text
 
-- **Pronouns on profile**: Not exposed in the meta.sr.ht GraphQL schema. The
-  field exists in the web UI but is not available to external API clients.
+---
+
+### pages.sr.ht
+
+- **Endpoint:** [https://pages.sr.ht/graphql](https://pages.sr.ht/graphql)
+
+**Tasks:**
+
+- Show the authenticated user’s published sites
+- Display site metadata, publishing status, and access control where supported
+- For managing Pages sites, not browsing public project discovery
+
+---
+
+### Donation Page / In-App Purchases
+
+- Add a donation/support page once the App Store / StoreKit setup is ready
+
+---
+
+## Out of Scope
 
-- **Revoke personal access tokens**: The revokePersonalAccessToken mutation is
-  marked @internal in the meta.sr.ht schema and is not accessible to external
-  clients.
+- Universal links (requires Sourcehut to host an apple-app-site-association
+  file)
+- Push notifications for builds and tickets (requires a backend relay server)
+- Contribution activity / GitHub-style heatmap (no aggregate endpoint,
+  impractical to compute)
+- Explore / search (hub.sr.ht) (no public discovery API)
+- Pronouns on profile (not in GraphQL schema)
+- Revoke personal access tokens (`@internal` in schema, inaccessible)