docs: document fork and upstream workflow

CLAUDE.md

@@ -186,10 +186,21 @@ modules/<module>/        # specs grouped by product module (auth, sso, marketing
 
 ## Git Workflow
 
-GitHub is the **only** remote — this repo no longer mirrors to Bitbucket. See **`docs/dev/git-workflow.md`** for the full procedure. Key rules:
+Two roles, one repository. Use the part that matches how you have this cloned. See **`docs/dev/git-workflow.md`** for the full procedure.
+
+**Maintainer / core clone**
+
+- `origin` is `github.com:offloadmemory/agentfork.git`; a plain `git push` targets it.
+- Branch → PR into `main` (`gh pr create --base main`). Never push to `main` directly; only the owner merges.
+
+**External contributor (fork)**
+
+- `origin` is your fork; `upstream` is `offloadmemory/agentfork` with pushes disabled (`git remote set-url --push upstream no_push`).
+- Branch from `upstream/main`, push to `origin`, open the PR against `upstream` `main`.
+- Sync your fork with `git fetch upstream && git merge --ff-only upstream/main && git push origin main`.
+
+**Both**
 
-- `origin` is `github.com:offloadmemory/agentfork.git`. A plain `git push` targets GitHub.
-- Work on a feature branch; open a PR into `main` (`gh pr create --base main`). Don't push to `main` directly; only the user merges.
 - `.env.example` holds placeholders only — never commit real secrets. If GitHub push protection blocks a key, stop and tell the user; don't use the allow-secret bypass yourself.
 
 ## Code Style

CONTRIBUTING.md

@@ -45,12 +45,12 @@ Use the following prefixes for consistency:
 
 ### Rules
 
-1. **Branch from `main`** and keep it up to date:
+1. **Branch from the official `main`** (`upstream/main`) and keep your fork in sync:
    ```bash
-   git checkout main
-   git pull origin main
-   git checkout -b feat/your-feature
+   git fetch upstream
+   git checkout -b feat/your-feature upstream/main
    ```
+   Push the branch to your fork (`git push -u origin feat/your-feature`) and open the PR from your fork into `offloadmemory/agentfork:main`. See [docs/dev/git-workflow.md](docs/dev/git-workflow.md).
 2. **One concern per PR** — do not mix unrelated changes.
 3. **Keep branches short-lived** — aim to merge within a few days.
 4. **Delete branches after merge** — GitHub can do this automatically.
@@ -101,4 +101,4 @@ We use [Conventional Commits](https://www.conventionalcommits.org/):
 
 ## Questions?
 
-Open a [Discussion](https://github.com/kartikmanimuthu/agentfork/discussions) or reach out in an issue.
+Open a [Discussion](https://github.com/offloadmemory/agentfork/discussions) or reach out in an issue.

README.md

@@ -198,7 +198,7 @@ agentfork/                        # Nx workspace root
 ### 1. Clone and install
 
 ```bash
-git clone https://github.com/kartikmanimuthu/agentfork.git
+git clone https://github.com/offloadmemory/agentfork.git
 cd agentfork
 bun install
 ```
@@ -392,8 +392,8 @@ E2e specs are grouped by module (`@auth`, `@sso`, `@marketing`, `@docs`, `@navig
 ## Contributing & Support
 
 - 🤝 **Contributing** — see [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and standards.
-- 💬 **Questions & help** — see [SUPPORT.md](SUPPORT.md) or open a [Discussion](https://github.com/kartikmanimuthu/agentfork/discussions).
-- 🐛 **Bugs & features** — open an [issue](https://github.com/kartikmanimuthu/agentfork/issues/new/choose).
+- 💬 **Questions & help** — see [SUPPORT.md](SUPPORT.md) or open a [Discussion](https://github.com/offloadmemory/agentfork/discussions).
+- 🐛 **Bugs & features** — open an [issue](https://github.com/offloadmemory/agentfork/issues/new/choose).
 - 🔒 **Security** — report privately per [SECURITY.md](SECURITY.md); never via public issues.
 - 📓 **Code of Conduct** — [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
 

docs/dev/git-workflow.md

@@ -1,23 +1,42 @@
-# Git Workflow — Committing & Pushing (GitHub)
+# Git Workflow — Committing & Pushing
 
-GitHub is the **only** remote. `origin` points at
-`git@github.com:offloadmemory/agentfork.git`, so a single `git push` lands there.
+Two roles, one repository. Use the section that matches how you have this cloned:
 
-> Audience: humans and AI agents. Follow the steps verbatim. Do not push, force-push, or rewrite history unless the user explicitly asks.
+- **Maintainer / core clone** — `origin` is the official repository; a bare `git push` lands there.
+- **External contributor (fork)** — `origin` is your fork; `upstream` is the official repository and pushes to it are disabled.
+
+> Audience: humans and AI agents. Follow the steps for your role verbatim. Do not push, force-push, or rewrite history unless the user explicitly asks.
 
 ## Remote layout
 
+### Maintainer / core clone
+
 | Remote | Fetch | Push | Use for |
 | --- | --- | --- | --- |
 | `origin` | GitHub | GitHub | Everything. A bare `git push` targets GitHub. |
 
-Verify with `git remote -v`. If `origin` is missing, recreate it:
+`origin` is `git@github.com:offloadmemory/agentfork.git`. Verify with `git remote -v`; if it is missing, recreate it:
 
 ```bash
 git remote add origin git@github.com:offloadmemory/agentfork.git
 ```
 
-## Standard commit + push
+### External contributor (fork)
+
+| Remote | Points to | Fetch | Push |
+| --- | --- | --- | --- |
+| `origin` | `https://github.com/<your-user>/agentfork.git` (your fork) | yes | yes |
+| `upstream` | `https://github.com/offloadmemory/agentfork.git` (official) | yes | **disabled** (`no_push`) |
+
+Set the remotes up once, after forking and cloning:
+
+```bash
+git remote add upstream https://github.com/offloadmemory/agentfork.git
+git remote set-url --push upstream no_push
+git remote -v    # upstream must show "no_push" on the push line
+```
+
+## Standard commit + push — maintainer / core clone
 
 ```bash
 git status                       # confirm what you're committing
@@ -26,11 +45,41 @@ git commit -m "type(scope): summary"   # see commit message rules below
 git push                         # → GitHub
 ```
 
+## Contributor flow — fork
+
+1. Update your view of the official repository:
+   ```bash
+   git fetch upstream
+   ```
+2. Create a branch from the official `main` (not from your fork's `main`):
+   ```bash
+   git checkout -b feat/<topic> upstream/main
+   ```
+3. Make your changes, then commit them (see commit message rules below).
+4. Push the branch to your fork:
+   ```bash
+   git push -u origin feat/<topic>
+   ```
+5. Open a pull request: base repository `offloadmemory/agentfork`, base branch `main`, head repository your fork, compare branch `feat/<topic>`.
+
+### Keeping your fork's `main` up to date
+
+Your fork's `main` should always match the official `main`:
+
+```bash
+git fetch upstream
+git checkout main
+git merge --ff-only upstream/main
+git push origin main
+```
+
+If `--ff-only` fails, your `main` has commits the official repository does not have. Stop and ask the project owner before doing anything else. Do not force-push.
+
 ## Before you push — checklist
 
 1. **Verify the work.** Run `bun run typecheck` and `bun run test` (or `bun run verify`). Never claim success without seeing the commands pass.
 2. **No secrets.** Never commit real credentials. `.env.example` holds *placeholders only*. GitHub push protection will block real keys (e.g. `AWS_BEARER_TOKEN_BEDROCK`, `AKIA...`). If blocked, **stop and tell the user** — do not use the allow-secret bypass URL on your own.
-3. **Branch, don't push to** `main` **directly.** Work on a feature branch and open a PR into `main` (`gh pr create --base main`). Only the user merges.
+3. **Branch, don't push to** `main` **directly.** Work on a feature branch and open a PR into `main`. Only the owner merges.
 
 ## Commit message rules