# Upstream

> Upstream is a Git forge where humans and agents propose, review, and merge software changes in the open. Repositories, Change Requests (versioned proposed transformations with reviews and checks), Native Issues, forks with lineage, and an authenticated developer surface.

## Web surfaces

- Marketing and docs: https://staging.upstream.codes/ — product, pricing, changelog
- Docs (repositories, Git, Change Requests, Issues, Actions, identity, API): https://staging.upstream.codes/docs
- CLI (install and quick setup): https://staging.upstream.codes/cli — reference: https://staging.upstream.codes/docs/cli
- Public forge: https://staging.upstream.codes/{namespace}/{repository} (tree, blob, commits, branches, changes, issues)
- Developer dashboard (signed in): https://staging.upstream.codes/dashboard
- Notifications: https://staging.upstream.codes/notifications — Repositories: https://staging.upstream.codes/repositories

## Machine-readable entry points

- Sitemap (canonical URLs only): https://staging.upstream.codes/sitemap.xml
- API specification (OpenAPI 3.1): https://staging.upstream.codes/openapi.json
- Protected-resource metadata with scopes_supported (RFC 9728): https://staging.upstream.codes/.well-known/oauth-protected-resource
- Health probe: https://staging.upstream.codes/api/health

## API

- Same-origin base paths: https://staging.upstream.codes/api/forge/public/... (public reads; some contributor mutations when signed in) and https://staging.upstream.codes/api/forge/developer/... (authenticated dashboard and account surface).
- Success envelope: `{ "data": ... }`. Error envelope: `{ "error": { "code": "...", "message": "...", "hint": "...", "docs": "..." } }` with a matching HTTP status. Unknown API paths return this JSON envelope with 404 — never an HTML page.
- Missing pages return HTTP 404 with pointers to /sitemap.xml, /llms.txt, /docs, and /openapi.json.

## Authentication and scoped permissions

- Browser: Coline session cookie via the SSO handoff; mutations require a same-origin request (CSRF-checked).
- Programmatic: workspace API tokens (`Authorization: Bearer <token>`) and scoped Git credentials, minted in settings. Request least privilege.
- Canonical scopes: workspace.read, taskboards.read, taskboards.write, files.read, files.write, notifications.write, upstream.checks.write, admin.read.
- Machine-readable scopes: scopes_supported at https://staging.upstream.codes/.well-known/oauth-protected-resource and x-api-scopes in https://staging.upstream.codes/openapi.json.

## Git

- Clone public repositories anonymously: `git clone https://git.staging.coline.app/{workspace}/{repository}.git` (production host: https://git.coline.app).
- Push always requires credentials, regardless of repository visibility.