Update TODO and README

README.md

···
 
 ## 4. Tech Stack (TypeScript)
 
-| Component         | Library               | Purpose                                                      |
-| :---------------- | :-------------------- | :----------------------------------------------------------- |
-| **Framework**     | **commander**         | Routing (tangled repo create).                               |
-| **API Client**    | **@atproto/api**      | Official XRPC client & session management.                   |
-| **Git Context**   | **git-url-parse**     | **New:** Parses remote URLs to extract the Tangled DID/NSID. |
-| **Git Ops**       | **simple-git**        | Wraps local git operations safely.                           |
-| **Validation**    | **zod**               | Validates inputs & generates schemas for LLMs.               |
-| **Interactivity** | **@inquirer/prompts** | Modern prompts for humans.                                   |
-| **Formatting**    | **cli-table3**        | **New:** For gh-style pretty tables in Human Mode.           |
+| Component         | Library               | Purpose                                                       |
+| :---------------- | :-------------------- | :------------------------------------------------------------ |
+| **Framework**     | **commander**         | Routing (tangled repo create).                                |
+| **API Client**    | **@atproto/api**      | Official XRPC client & session management.                    |
+| **Git Context**   | **git-url-parse**     | **New:** Parses remote URLs to extract the Tangled DID/NSID.  |
+| **Git Ops**       | **simple-git**        | Wraps local git operations safely.                            |
+| **Validation**    | **zod**               | Validates inputs & generates schemas for LLMs.                |
+| **Interactivity** | **@inquirer/prompts** | Modern prompts for humans.                                    |
+| **Formatting**    | **cli-table3**        | **New:** For gh-style pretty tables in Human Mode.            |
 | **OS Keychain**   | **keytar**            | **New:** To securely store session tokens in the OS keychain. |
 
 ## 5. Agent Integration (The "LLM Friendly" Layer)
···
 ### Rule 4: Flexible Input for Issue Bodies
 
 Following `gh`'s pattern, `tangled issue create` will support various ways to provide the issue body, making it LLM-friendly and flexible for scripting. It will accept:
--   `--body "Text"` or `-b "Text"` for a direct string.
--   `--body-file ./file.md` or `-F ./file.md` to read from a file.
--   `--body-file -` or `-F -` to read from standard input (stdin).
+
+- `--body "Text"` or `-b "Text"` for a direct string.
+- `--body-file ./file.md` or `-F ./file.md` to read from a file.
+- `--body-file -` or `-F -` to read from standard input (stdin).
 
 ### Summary of Improvements
 
···
 
 ### 1. (Resolved) SSH Key Management (`gh` Compatibility)
 
-*   **Original Question:** How does `gh` manage SSH keys, and can we follow that pattern?
-*   **Resolution:** Analysis shows that `gh` does *not* manage private keys. It facilitates uploading the user's *public* key to their GitHub account. The local SSH agent handles the private key.
-*   **Our Approach:** The `tangled ssh-key add` command follows this exact pattern. It provides a user-friendly way to upload a public key to `tangled.org`. This resolves the core of this issue, as it is compatible with external key managers like 1Password's SSH agent.
+- **Original Question:** How does `gh` manage SSH keys, and can we follow that pattern?
+- **Resolution:** Analysis shows that `gh` does _not_ manage private keys. It facilitates uploading the user's _public_ key to their GitHub account. The local SSH agent handles the private key.
+- **Our Approach:** The `tangled ssh-key add` command follows this exact pattern. It provides a user-friendly way to upload a public key to `tangled.org`. This resolves the core of this issue, as it is compatible with external key managers like 1Password's SSH agent.
 
 ### 2. (Decided) Secure Session Storage
 
-*   **Original Question:** How should we securely store the AT Proto session token?
-*   **Resolution:** Storing sensitive tokens in plaintext files is not secure.
-*   **Our Approach:** The CLI will use the operating system's native keychain for secure storage (e.g., macOS Keychain, Windows Credential Manager, or Secret Service on Linux). A library like `keytar` will be used to abstract the platform differences.
+- **Original Question:** How should we securely store the AT Proto session token?
+- **Resolution:** Storing sensitive tokens in plaintext files is not secure.
+- **Our Approach:** The CLI will use the operating system's native keychain for secure storage (e.g., macOS Keychain, Windows Credential Manager, or Secret Service on Linux). A library like `keytar` will be used to abstract the platform differences.
 
 ### 3. (Decided) Configuration Resolution Order
 
-*   **Original Question:** How should settings be resolved from different sources?
-*   **Resolution:** A clear precedence order is necessary.
-*   **Our Approach:** The CLI will resolve settings in the following order of precedence (highest first):
-    1.  Command-line flags (e.g., `--repo-did ...`)
-    2.  Environment variables (e.g., `TANGLED_REPO_DID=...`)
-    3.  Project-specific config file (e.g., `.tangled/config.yml` in the current directory)
-    4.  Global user config file (e.g., `~/.config/tangled/config.yml`)
+- **Original Question:** How should settings be resolved from different sources?
+- **Resolution:** A clear precedence order is necessary.
+- **Our Approach:** The CLI will resolve settings in the following order of precedence (highest first):
+  1.  Command-line flags (e.g., `--repo-did ...`)
+  2.  Environment variables (e.g., `TANGLED_REPO_DID=...`)
+  3.  Project-specific config file (e.g., `.tangled/config.yml` in the current directory)
+  4.  Global user config file (e.g., `~/.config/tangled/config.yml`)
 
-### 4. (Outstanding) Web-based Authentication Flow
+### 4. (Decided for V1) Authentication Flow: App Passwords (PDS)
 
-*   **Original Question:** Can we allow auth through a web browser?
-*   **Status:** This remains an outstanding issue. The standard AT Protocol authentication flow is based on user handles and app passwords, not a third-party OAuth2 flow like GitHub CLI uses.
-*   **Path Forward:** Implementing a web-based auth flow would require custom development on the `tangled.org` service itself to securely generate and transmit a session token back to the CLI. This is out of scope for the initial version of the CLI.
+- **Original Question:** Can we allow auth through a web browser?
+- **Resolution:** For the initial version, the CLI will use **App Passwords** for authentication. This is the standard and simplest method for third-party AT Protocol clients and aligns with existing practices.
+- **`tangled auth login` Flow:** When running `tangled auth login`, the CLI will prompt the user for their **PDS handle** (e.g., `@mark.bsky.social`) and an **App Password**.
+- **Generating an App Password:** Users typically generate App Passwords from their PDS's settings (e.g., in the official Bluesky app under "Settings -> App Passwords", or on their self-hosted PDS web interface). The CLI **does not** generate app passwords.
+- **Session Management:** The session established is with the user's PDS, and this authenticated session is then used to interact with `tangled.org`'s App View/Service.
+- **OAuth Support:** Implementing a web-based OAuth flow (similar to `gh`'s approach) is more complex and not a standard part of the AT Protocol client authentication flow. This approach is deferred for future consideration.
 
 ## 9. Future Expansion Opportunities
 
 The analysis of the `tangled.org` API revealed a rich set of features that are not yet part of the initial CLI plan but represent significant opportunities for future expansion. These include:
 
-*   **CI/CD Pipelines:** Commands to view pipeline status and manage CI/CD jobs.
-*   **Repository Secrets:** A dedicated command set for managing CI/CD secrets within a repository (`tangled repo secret ...`).
-*   **Advanced Git Operations:** Commands to interact with the commit log, diffs, branches, and tags directly via the API, augmenting local `git` commands.
-*   **Social & Feed Interactions:** Commands for starring repositories, reacting to feed items, and managing the user's social graph (following/unfollowing).
-*   **Label Management:** Commands to create, apply, and remove labels from issues and pull requests.
-*   **Collaboration:** Commands to manage repository collaborators.
-*   **Fork Management:** Commands for forking repositories and managing the sync status of forks.
+- **CI/CD Pipelines:** Commands to view pipeline status and manage CI/CD jobs.
+- **Repository Secrets:** A dedicated command set for managing CI/CD secrets within a repository (`tangled repo secret ...`).
+- **Advanced Git Operations:** Commands to interact with the commit log, diffs, branches, and tags directly via the API, augmenting local `git` commands.
+- **Social & Feed Interactions:** Commands for starring repositories, reacting to feed items, and managing the user's social graph (following/unfollowing).
+- **Label Management:** Commands to create, apply, and remove labels from issues and pull requests.
+- **Collaboration:** Commands to manage repository collaborators.
+- **Fork Management:** Commands for forking repositories and managing the sync status of forks.
 
 ## 10. Task Management
 
-We're bootstrapping task tracking with TODO.md, but will migrate all tasks into Tangled issues and dog food the product as soon as we have basic issue creation and listing working.
+We're bootstrapping task tracking with TODO.md, but will migrate all tasks into Tangled issues and dog food the product as soon as we have basic issue creation and listing working.

TODO.md

···
 This document outlines the development tasks for the Tangled CLI, based on the `README.md` and project goals.
 
 ## 1. Project Setup & Core Structure (Commander.js)
+
 - [ ] Initialize Node.js project.
 - [ ] Install `commander` for CLI routing.
 - [ ] Implement basic CLI command structure (e.g., `tangled --version`, `tangled --help`).
···
 - [ ] Configure linting and formatting (ESLint, Prettier).
 
 ## 2. Authentication (Auth)
+
 - [ ] Implement `tangled auth login` command.
-    - [ ] Implement session storage using an OS keychain library (e.g., `keytar`) for secure, cross-platform token management.
-    - [ ] Integrate `@atproto/api` for XRPC client and session management.
-    - [ ] Investigate web browser authentication flow.
+  - [ ] Collect user's PDS handle and app password.
+  - [ ] Implement session storage using an OS keychain library (e.g., `keytar`) for secure, cross-platform token management.
+  - [ ] Integrate `@atproto/api` for XRPC client and session management.
 - [ ] Implement `tangled auth logout` command.
 
 ## 3. Git SSH Key Management
+
 - [ ] Implement `tangled ssh-key add <public-key-path>` command.
-    - [ ] This command should upload the provided public SSH key to the user's tangled.org account via the API, similar to how `gh ssh-key add` works.
-    - [ ] The CLI is not responsible for generating SSH keys or managing the local ssh-agent; users are expected to handle these steps externally.
+  - [ ] This command should upload the provided public SSH key to the user's tangled.org account via the API, similar to how `gh ssh-key add` works.
+  - [ ] The CLI is not responsible for generating SSH keys or managing the local ssh-agent; users are expected to handle these steps externally.
 - [ ] Implement `tangled ssh-key verify` command.
-    - [ ] This command should execute `ssh -T [e-mail]`, parse the DID from its output, and then resolve that DID to a Bluesky handle, displaying the result to the user.
+  - [ ] This command should execute `ssh -T [e-mail]`, parse the DID from its output, and then resolve that DID to a Bluesky handle, displaying the result to the user.
 - [ ] Ensure all Git operations leverage SSH keys for authentication, as `tangled.org` exclusively supports SSH for Git.
 
 ## 4. Context Engine (Git Integration)
+
 - [ ] Integrate `git-url-parse` to resolve Tangled DID/NSID from `.git/config` remote URLs.
 - [ ] Develop a "Context Resolver" module to infer repository context (DID) from the current working directory.
 - [ ] Implement fallback mechanisms if no git remote is found or DID cannot be resolved (error handling).
···
 - [ ] Implement functionality to resolve a DID (e.g., `did:plc:b2mcbcamkwyznc5fkplwlxbf`) into a human-readable Bluesky handle (will be reused by `tangled ssh-key verify`).
 
 ## 5. Repository Management
+
 - [ ] Implement `tangled repo create <repo-name>` command.
 - [ ] Implement `tangled repo view` command (display repo details).
-    - [ ] Support `--json` output with field filtering (e.g., `--json name,cloneUrl,description`) using `lodash/pick`).
+  - [ ] Support `--json` output with field filtering (e.g., `--json name,cloneUrl,description`) using `lodash/pick`).
 
 ## 6. Issue Management
+
 - [ ] Implement `tangled issue create "<title>" [--body "<body>" | --body-file <file> | -F -]` command.
 - [ ] Implement `tangled issue list [--json "id,title"]` command.
-    - [ ] Support `--json` output with field filtering.
+  - [ ] Support `--json` output with field filtering.
 
 ## 7. Pull Request Management
 
 This section outlines the phased implementation for Pull Request (PR) support, following `gh` CLI patterns.
 
 ### Phase 1: Creating a Pull Request from a Branch (Author Workflow)
+
 - [ ] Implement `tangled pr create --base <base-branch> --head <head-branch> --title <title> [--body <body> | --body-file <file> | -F -]` command.
-    - [ ] Generate the `git diff` patch between the `--head` and `--base` branches.
-    - [ ] Upload the generated patch as a blob using `com.atproto.repo.uploadBlob` (or equivalent).
-    - [ ] Create a `sh.tangled.repo.pull` record using `com.atproto.repo.createRecord`, including `target` (repo and base branch), `source` (head branch and SHA), `title`, `body`, and the `patchBlob` reference.
+  - [ ] Generate the `git diff` patch between the `--head` and `--base` branches.
+  - [ ] Upload the generated patch as a blob using `com.atproto.repo.uploadBlob` (or equivalent).
+  - [ ] Create a `sh.tangled.repo.pull` record using `com.atproto.repo.createRecord`, including `target` (repo and base branch), `source` (head branch and SHA), `title`, `body`, and the `patchBlob` reference.
 - [ ] Implement `tangled pr list [--json <fields>]` command to list pull requests for the current repository.
-    - [ ] Use `com.atproto.repo.listRecords` with `collection: "sh.tangled.repo.pull"`.
+  - [ ] Use `com.atproto.repo.listRecords` with `collection: "sh.tangled.repo.pull"`.
 - [ ] Implement `tangled pr view <id> [--json <fields>]` command to display detailed information about a specific pull request.
-    - [ ] Use `com.atproto.repo.getRecord` for the `sh.tangled.repo.pull` record.
-    - [ ] Fetch associated comments using `com.atproto.repo.listRecords` with `collection: "sh.tangled.repo.pull.comment"`.
+  - [ ] Use `com.atproto.repo.getRecord` for the `sh.tangled.repo.pull` record.
+  - [ ] Fetch associated comments using `com.atproto.repo.listRecords` with `collection: "sh.tangled.repo.pull.comment"`.
 
 ### Phase 2: Working as a Reviewer (Commenting)
+
 - [ ] Implement `tangled pr comment <id> [--body <body> | --body-file <file> | -F -]` command.
-    - [ ] Create a `sh.tangled.repo.pull.comment` record using `com.atproto.repo.createRecord`, linking it to the pull request's AT-URI.
+  - [ ] Create a `sh.tangled.repo.pull.comment` record using `com.atproto.repo.createRecord`, linking it to the pull request's AT-URI.
 - [ ] Implement `tangled pr review <id> --comment <comment> [--approve | --request-changes]` command.
-    - [ ] Create a `sh.tangled.repo.pull.comment` record.
-    - [ ] Update the `sh.tangled.repo.pull.status` record (if applicable) to reflect approval or requested changes. (Further API research might be needed to map approve/request-changes to status updates).
+  - [ ] Create a `sh.tangled.repo.pull.comment` record.
+  - [ ] Update the `sh.tangled.repo.pull.status` record (if applicable) to reflect approval or requested changes. (Further API research might be needed to map approve/request-changes to status updates).
 
 ### Phase 3: Responding to a Review (Author Workflow)
+
 - [ ] This phase primarily involves local Git operations (pushing new commits) and using `tangled pr comment` for clarifications, which are covered by existing or planned commands.
 
 ## 8. Output & LLM Integration
+
 - [ ] Implement output formatting based on `is-interactive` check.
-    - [ ] "Human Mode" (TTY): Use `cli-table3` for pretty tables.
-    - [ ] "Machine Mode" (Pipe/`--json`): Plain text or JSON output.
+  - [ ] "Human Mode" (TTY): Use `cli-table3` for pretty tables.
+  - [ ] "Machine Mode" (Pipe/`--json`): Plain text or JSON output.
 - [ ] Implement `--json` flag for structured output.
 - [ ] Implement `--no-input` flag to force CLI to error on unresolved context or missing flags (Fail Fast, Fail Loud principle).
 
 ## 9. Testing
+
 - [ ] Set up a testing framework (e.g., Jest, Vitest).
 - [ ] Write unit tests for core modules (Auth, Context Resolver, API client).
 - [ ] Write integration tests for CLI commands.
 
 ## 10. Documentation & Deployment
+
 - [ ] Generate CLI help documentation (`commander` usually handles this).
 - [ ] Consider packaging/distribution strategy (npm, standalone binary).
 
 ## 11. Outstanding Issues / Future Considerations (from README)
+
 - [ ] Secure cross-platform AT Proto session storage (OS keychain).
 - [ ] Git authentication management similar to GitHub CLI (SSH keys, 1Password integration).
 - [ ] Define clear precedence order for settings resolution (local config, home folder, CLI flags).
-- [ ] Consider adding extensions/plugins (Out of Scope for V1, but keep in mind).
+- [ ] Consider adding extensions/plugins (Out of Scope for V1, but keep in mind).