Add a no-redesign semantic layer that makes native Gitea collaboration Hop-first

Hop-State: A_06FN45YJ09WC2QFGJM27VE8
Hop-Proposal: R_06FN45WVVTHC245S2BK503G
Hop-Task: T_06FN3MVGY3MT82ESQ89BND0
Hop-Attempt: AT_06FN3MVGY092BFA5MR9C7EG

docs/adr/0002-gitea-native-semantic-layer.md

@@ -0,0 +1,64 @@
+# ADR 0002: Preserve Gitea's design and replace its collaboration semantics
+
+- Status: Accepted
+- Date: 2026-07-11
+
+## Context
+
+HopWeb needs to become Hop-native without spending early product effort on a
+new visual shell or maintaining broad Gitea template forks. Gitea already has a
+coherent, accessible component system and familiar repository navigation.
+
+The first product distinction is conceptual rather than visual. Hop users work
+with tasks, attempts, checkpoints, proposals, evidence, and accepted outcomes.
+Gitea exposes closely related infrastructure as issues, branches, commits, pull
+requests, Actions, and merges.
+
+## Decision
+
+Keep Gitea's existing layout, typography, color, spacing, icons, responsive
+behavior, and component states unchanged.
+
+Load a small same-origin semantic adapter through Gitea's supported custom
+footer template. The adapter changes visible labels and matching accessibility
+metadata while preserving the underlying routes and behavior:
+
+| Gitea element | Hop meaning |
+| --- | --- |
+| Code | Files |
+| Issues | Tasks |
+| Branches | Attempts |
+| Commits | Checkpoints |
+| Pull Requests | Proposals |
+| Actions | Evidence |
+| Merge Pull Request | Accept Proposal |
+
+On repository home pages, add a compact `Hop workflow` summary using Gitea's
+existing sidebar classes and the live navigation links and counts already
+rendered by Gitea. Do not add custom CSS.
+
+Set the application name to `Hop`, while retaining Gitea attribution and its
+standard administrative and Git compatibility surfaces.
+
+## Consequences
+
+- Existing Gitea behavior, responsiveness, themes, and accessibility remain
+  available.
+- The first Hop experience ships without a deep template fork.
+- URLs and APIs remain Gitea-compatible even when their visible names change.
+- DOM selectors and English labels are version-sensitive and require a smoke
+  test when upgrading Gitea.
+- As Hop gains distinct task and state behavior, individual semantic elements
+  can move from adapted Gitea routes to native server-backed routes without a
+  simultaneous visual redesign.
+
+## Guardrails
+
+- Do not add CSS to the semantic adapter.
+- Never rename an element unless its behavior is meaningfully compatible with
+  the corresponding Hop concept.
+- Keep accessible names and tooltips synchronized with visible labels.
+- Scope text replacement to navigation, headings, menus, labels, breadcrumbs,
+  and buttons. Never rewrite repository content or user-authored prose.
+- Verify the adapter against the pinned Gitea version before every upgrade.
+

docs/gitea-hop-native.md

@@ -0,0 +1,55 @@
+# Hop-native Gitea semantics
+
+HopWeb keeps Gitea's existing interface design and changes the meaning of its
+collaboration elements. No custom stylesheet, theme, component library, or
+layout override is installed.
+
+## Install
+
+From the project root:
+
+```sh
+./deploy/gitea/install-hop-native.sh
+```
+
+Set `ENV_FILE` when the Compose environment is stored elsewhere:
+
+```sh
+ENV_FILE=/path/to/environment ./deploy/gitea/install-hop-native.sh
+```
+
+The installer copies the adapter into Gitea's persistent custom directory,
+sets the application name to `Hop`, restarts Gitea, and waits for a healthy
+response. Re-run it after editing the adapter or replacing the Gitea volume.
+
+## Semantic mapping
+
+| Native route and behavior | Hop label |
+| --- | --- |
+| Repository code | Files |
+| Issues | Tasks |
+| Branches | Attempts |
+| Commits | Checkpoints |
+| Pull requests | Proposals |
+| Actions | Evidence |
+| Merge pull request | Accept proposal |
+
+The adapter updates visible text, document titles, form placeholders,
+tooltips, and ARIA labels. It scopes replacements to Gitea navigation,
+headings, menus, breadcrumbs, labels, and buttons, so repository content and
+user-authored prose remain unchanged.
+
+Repository home pages also receive a `Hop workflow` group in the existing
+Gitea sidebar. It uses Gitea's own classes, links, icons, and live counts.
+
+## Upgrade check
+
+After changing the pinned Gitea version:
+
+1. run the installer;
+2. confirm Tasks, Proposals, and Evidence in repository navigation;
+3. confirm Attempts and Checkpoints in the Files view;
+4. confirm proposal creation and acceptance labels;
+5. inspect browser console errors; and
+6. test a narrow viewport and keyboard navigation.
+