docs: prepare v0.5.0 Git workflow release

AGENTS.md

@@ -10,13 +10,13 @@ This app manages Git-backed **source/configuration** for Compose stacks. It is *
 
 ## Current phase
 
-**PR #4 — Git workflow** is the active product phase (commit, safe push, conflict protection, stack-scoped history,
-Changes UI). PR #2 (application foundation) and PR #3 (source workspace) are done, including the dashboard, organised
-Stacks list and settings split. Do not build deployment routing, secrets providers, runtime watch or PWA work ahead of
-their phases.
+**PR #5 — Deployment routing** is the next active product phase (DeploymentProvider, Portainer/generic webhooks,
+forge webhook receiver, relevance rules, selective deploy). PR #2 (application foundation), PR #3 (source workspace)
+and PR #4 (Git workflow: commit, safe push, conflict protection, stack history, Changes UI; released in v0.5.0) are
+done. Do not build secrets providers, runtime watch or PWA work ahead of their phases.
 
 See [docs/plans/MVP_PLAN.md](docs/plans/MVP_PLAN.md) and the code layout in
-[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#code-layout-implemented-in-pr-2).
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#code-layout-implemented-in-pr-2-extended-through-v050).
 
 ## Working in the code
 

README.md

@@ -12,12 +12,17 @@ It is **not** a Portainer / Komodo / Arcane / Docker UI replacement. Those syste
 
 Early development (0.x).
 
-**Already available:** first-run setup, workspaces, encrypted credentials, Git repository connections
+**Available today:** first-run setup, workspaces, encrypted credentials, Git repository connections
 (GitHub / Gitea / Forgejo over HTTPS), stacks, dashboard, organised Stacks list, settings, a VS Code-style editor with
-drafts and Compose validation, stack docs, an environment inventory, and change review (diffs).
+drafts and Compose validation, stack docs and an environment inventory.
 
-**Coming in v0.5.0:** committing drafts, safe push, and Git history. Deployment routing (deploy only the stacks a
-commit changed) follows the Git workflow phase; see the [roadmap](docs/plans/MVP_PLAN.md).
+**New in v0.5.0, the Git workflow:** review drafts on the Changes tab, commit them with your own Git identity
+(validation errors block, warnings need acknowledgement), and push safely to the tracked branch. Stack Manager never
+force pushes, stops when the remote branch has changed, and keeps your drafts whatever happens. Each stack has a
+History tab with the commits and diffs that touched it. See [Git workflow](docs/GIT_WORKFLOW.md).
+
+**Next:** deployment routing, which deploys only the stacks a commit changed through Portainer or a generic
+webhook. See the [roadmap](docs/plans/MVP_PLAN.md).
 
 **Documentation:** [uniskela.com/docs/stack-manager](https://uniskela.com/docs/stack-manager/) (source in
 [docs/](docs/index.md)).
@@ -26,6 +31,7 @@ commit changed) follows the Git workflow phase; see the [roadmap](docs/plans/MVP
 | --- | --- |
 | [Installation](docs/installation.md) | Run the published container image with Docker Compose |
 | [Getting started](docs/getting-started.md) | First run, connecting a repository, stacks and the editor |
+| [Git workflow](docs/GIT_WORKFLOW.md) | Commit, push, remote changes and stack history |
 | [Self-hosting reference](docs/SELF_HOSTING.md) | Configuration, data directory, reverse proxy, upgrades |
 | [Product](docs/PRODUCT.md) / [Architecture](docs/ARCHITECTURE.md) | What it is (and is not), and how it is built |
 | [Docs index](docs/INDEX.md) | Every design, planning and operations document |

docs/ARCHITECTURE.md

@@ -117,7 +117,7 @@ Self-hosted env examples (names indicative):
 
 No design around ephemeral serverless filesystem.
 
-## Code layout (implemented in PR #2)
+## Code layout (implemented in PR #2, extended through v0.5.0)
 
 ```text
 src/
@@ -126,16 +126,19 @@ src/
     api/…/route.ts          # every handler wrapped by defineRoute (auth default-deny, origin check, zod)
     styles/                 # tokens.css → base.css → components.css → shell.css (no inline styles; lint-enforced)
   shared/source/            # pure path rules, secret-file policy, Compose/YAML analysis (server + browser)
+  shared/git-*.ts           # Git workflow and history response contracts shared with the Changes/History UI
   ui/                       # UI components; may not import src/server/*
     primitives/             # Button, Alert, Section, PageHeader, Breadcrumbs, EmptyState, ConfirmButton, StatusPill
     shell/                  # signed-in app shell: sidebar (wide) / top bar + drawer (narrow)
-    source/                 # stack editor (CodeMirror 6), file tree, docs, changes, discovery
+    source/                 # stack editor (CodeMirror 6), file tree, docs, changes (commit/push), history, discovery
   server/
     config/                 # env parsing and validation
     domain/                 # entities, validation, errors — no framework/persistence imports
     application/            # services + persistence ports (ports.ts); depend on ports, not Drizzle
+                            #   (GitWorkflowService: draft commit/push; GitHistoryService: stack-scoped history)
     persistence/            # Drizzle schema; sqlite/ adapters implement the ports
-    providers/git/          # GitProvider capability interface, registry, hardened git CLI runner
+    providers/git/          # GitProvider interface, registry, hardened git CLI, isolated mutations, repository lock,
+                            #   history reader
     jobs/                   # lease-based in-process worker (ADR 0002)
     security/               # AES-256-GCM secret box, Argon2id, session tokens, redaction, path + network policy
     observability/          # structured JSON logger (redacted)