revamp markdown project files

5 files changed, 75 insertions, 204 deletions

diff --git a/Hutch.xcodeproj/project.pbxproj b/Hutch.xcodeproj/project.pbxproj
index 23a2d62..08b7a12 100644
--- a/Hutch.xcodeproj/project.pbxproj
+++ b/Hutch.xcodeproj/project.pbxproj
@@ -7,7 +7,6 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
-		8B2F89622F69DEA900FC0253 /* TODO.md in Resources */ = {isa = PBXBuildFile; fileRef = 8B2F89612F69DEA900FC0253 /* TODO.md */; };
 		8B2F89662F69DEB900FC0253 /* LICENSE in Resources */ = {isa = PBXBuildFile; fileRef = 8B2F89632F69DEB900FC0253 /* LICENSE */; };
 		8B2F89672F69DEB900FC0253 /* README.md in Resources */ = {isa = PBXBuildFile; fileRef = 8B2F89642F69DEB900FC0253 /* README.md */; };
 		8B2F89682F69DEB900FC0253 /* SECURITY.md in Resources */ = {isa = PBXBuildFile; fileRef = 8B2F89652F69DEB900FC0253 /* SECURITY.md */; };
@@ -24,7 +23,6 @@
 /* End PBXContainerItemProxy section */
 
 /* Begin PBXFileReference section */
-		8B2F89612F69DEA900FC0253 /* TODO.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = TODO.md; sourceTree = "<group>"; };
 		8B2F89632F69DEB900FC0253 /* LICENSE */ = {isa = PBXFileReference; lastKnownFileType = text; path = LICENSE; sourceTree = "<group>"; };
 		8B2F89642F69DEB900FC0253 /* README.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = README.md; sourceTree = "<group>"; };
 		8B2F89652F69DEB900FC0253 /* SECURITY.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = SECURITY.md; sourceTree = "<group>"; };
@@ -86,7 +84,6 @@
 				8B2F89632F69DEB900FC0253 /* LICENSE */,
 				8B2F89642F69DEB900FC0253 /* README.md */,
 				8B2F89652F69DEB900FC0253 /* SECURITY.md */,
-				8B2F89612F69DEA900FC0253 /* TODO.md */,
 				8B4B28D32F6704280045FA19 /* Hutch */,
 				8B8182B82F6B73F3000AE049 /* HutchTests */,
 				8B4B28D22F6704280045FA19 /* Products */,
@@ -194,7 +191,6 @@
 			isa = PBXResourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
-				8B2F89622F69DEA900FC0253 /* TODO.md in Resources */,
 				8B2F89662F69DEB900FC0253 /* LICENSE in Resources */,
 				8B2F89672F69DEB900FC0253 /* README.md in Resources */,
 				8B2F89682F69DEB900FC0253 /* SECURITY.md in Resources */,
diff --git a/README.md b/README.md
index d1eadac..6efadf5 100644
--- a/README.md
+++ b/README.md
@@ -1,58 +1,88 @@
-# Hutch for Sourcehut
-Sourcehut on iOS
+# Hutch
+iOS client for SourceHut.
 
 [![builds.sr.ht status](https://builds.sr.ht/~ccleberg/Hutch.svg)](https://builds.sr.ht/~ccleberg/Hutch?)
 
-## Table of Contents
+## Overview
 
-- [Introduction](#introduction)
-- [Installation](#installation)
-- [Usage](#usage)
-- [Contributing](#contributing)
-- [License](#license)
-- [Contact](#contact)
+Hutch is a native SwiftUI app for browsing and managing SourceHut services on iPhone and iPad. It uses SourceHut's GraphQL APIs and stores your personal access token in the iOS keychain.
 
-## Introduction
+The app currently includes:
 
-**Hutch** is a native Swift client on iOS for [Sourcehut](https://sr.ht).
+- Home dashboard with assigned tickets, recent builds, and projects
+- Repository browsing for Git and Mercurial repositories
+- Repository details including README, references, commits, diffs, files, artifacts, and settings
+- Tracker and ticket browsing, ticket detail views, and tracker creation
+- Build job browsing, build detail views, and build submission
+- Inbox and mailing list reading flows
+- Paste browsing, creation, and detail views
+- Profile and account settings, including SSH keys, PGP keys, and personal access token management
+- Deep links for repositories, tickets, and build jobs
 
-## Installation
+Some SourceHut services are still browser-only from within Hutch. Unsupported areas currently open in Safari instead of rendering in-app.
 
-To get started with Hutch, follow these steps:
+## Requirements
+
+- Xcode with current iOS SDK support
+- iOS Simulator or physical iOS device
+- A SourceHut account
+- A SourceHut personal access token
+
+## Getting Started
+
+1. Clone the repository:
+
+   ```sh
+   git clone https://git.sr.ht/~ccleberg/Hutch
+   ```
 
-1. Clone the repository: `git clone
-   https://git.sr.ht/~ccleberg/Hutch`
 2. Open the project in Xcode.
-3. Run the app on your device or simulator.
+3. Build and run the app on a simulator or device.
+4. On first launch, create or paste a SourceHut personal access token.
+
+You can create a token at:
+
+- `https://meta.sr.ht/oauth/personal-access-tokens`
+
+## Using Hutch
+
+After signing in with a valid token, Hutch presents five primary areas:
 
-## Usage
+- `Home`: dashboard for projects, assigned tickets, recent builds, and inbox access
+- `Repositories`: browse, search, create, and manage repositories
+- `Tickets`: browse trackers, create trackers, and view ticket details
+- `Builds`: inspect build jobs and submit new builds
+- `More`: lists, pastes, settings, and external links for unsupported services
 
-Provide instructions on how to use the app. You might include:
+Authentication notes:
 
-- **Step 1**: To login, use a PAT in Sourcehut's portal:
-  https://meta.sr.ht/oauth2/personal-token
-- **Step 2**: Navigate the app the same way you'd navigate Sourcehut.
-- **Step 3**: If something doesn't work as expected, send us an email!
+- Hutch validates the token against `meta.sr.ht` before saving it
+- The token is stored in the iOS keychain
+- `Reset App Data` removes saved token data, caches, cookies, and local web data from the device
+
+## Development
+
+The project is an Xcode app with tests under `HutchTests`.
+
+Typical workflow:
+
+1. Open the workspace or project in Xcode.
+2. Select the Hutch app scheme.
+3. Build the app.
+4. Run the test plan in `Hutch/HutchTests.xctestplan`.
 
 ## Contributing
 
-Contributions are welcome! Please follow these steps:
+Contributions are welcome. Keep changes scoped, include tests when behavior changes, and open a pull request with a clear summary of the user-facing impact.
 
-1. Fork the repository.
-2. Create a new branch for your feature (`git checkout -b feature-xyz`).
-3. Make your changes.
-4. Commit your changes and push to the branch.
-5. Open a pull request.
+## Security
+
+If you discover a security issue, see [SECURITY.md](SECURITY.md).
 
 ## License
 
-This project is licensed under the GPL 3.0 or later License. See the
-[LICENSE](LICENSE) file for more information.
+This project is licensed under the GPL 3.0 or later. See [LICENSE](LICENSE).
 
 ## Contact
 
-For questions or feedback, please reach out to [[email protected]].
-
----
-
-Thank you for checking out **Hutch**! We hope you find it useful and enjoyable.
+Questions or feedback: [email protected]
diff --git a/ROADMAP.md b/ROADMAP.md
deleted file mode 100644
index 46af8dd..0000000
--- a/ROADMAP.md
+++ /dev/null
@@ -1,98 +0,0 @@
-# Hutch Roadmap
-
-## Version 1.0 Goal
-
-Ship a stable SourceHut mobile client with strong support for the most active
-day-to-day workflows:
-
-- Browse and manage repositories
-- Browse and manage tickets
-- Browse and manage builds
-- Support both Git and Mercurial repositories
-- Provide dependable sharing and navigation
-
-Version 1.0 does not need to cover every SourceHut service.
-
----
-
-## Release Strategy
-
-### Phase 1: Ship Readiness
-
-Focus on quality, not new surface area.
-
-#### Core release checklist
-
-- Verify authentication flow on simulator and physical device
-- Verify reset/sign-out/reset-app-data flow on simulator and physical device
-- Verify all destructive actions have confirmation and correct follow-up state
-- Verify all create flows succeed end-to-end:
-  - Git repository
-  - Mercurial repository
-  - Tracker
-  - Ticket
-  - Build submission
-- Verify build retry and edit/resubmit flows
-- Verify repository sharing links for:
-  - Repository
-  - Commit
-  - File
-- Verify sharing links for:
-  - 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
-  - WebView rendering performance
-
-#### UI/UX polish checklist
-
-- Tighten wording and error messages across create/edit flows
-- 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
-- Confirm keyboard behavior and dismissal in all creation sheets
-
-#### App Store readiness
-
-- Finalize app icon and screenshots
-- Finalize App Store copy
-- Finalize privacy details
-- 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.
-
-#### Recommended priority
-
-1. Exact repository lookup
-2. paste.sr.ht
-3. lists.sr.ht
-
-#### Why
-
-- Exact repository lookup solves a real gap created by the lack of public
-  discovery APIs
-- 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.
-
-- 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
diff --git a/SCOPE.md b/SCOPE.md
new file mode 100644
index 0000000..f2d86f8
--- /dev/null
+++ b/SCOPE.md
@@ -0,0 +1,10 @@
+# Out of Scope Features
+
+- 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)
diff --git a/TODO.md b/TODO.md
deleted file mode 100644
index 65a7617..0000000
--- a/TODO.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# TODO
-
----
-
-## 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
-
----
-
-### lists.sr.ht
-
-- **Endpoint:** [https://lists.sr.ht/graphql](https://lists.sr.ht/graphql)
-- **Scope:** `LISTS:RO`
-
-**Tasks:**
-
-- Show the authenticated user’s mailing lists
-- Allow browsing email threads
-- Display individual emails as plain text
-
----
-
-### 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
-
-- 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)