Add "Home"

Home.md

@@ -0,0 +1,112 @@
+# go-scm
+
+**Module:** `forge.lthn.ai/core/go-scm`  
+**Go:** 1.25.5  
+**Licence:** EUPL-1.2
+
+Multi-platform source control abstraction for the Core ecosystem. Provides unified Forgejo and Gitea clients, AgentCI orchestration via the Clotho Protocol, parallel git operations, a poll-dispatch job runner, and a data collection subsystem.
+
+## Package Structure
+
+| Package | Import Path | Purpose |
+|---------|-------------|---------|
+| `forge/` | `forge.lthn.ai/core/go-scm/forge` | Forgejo SDK wrapper -- repos, issues, PRs, labels, webhooks, organisations |
+| `gitea/` | `forge.lthn.ai/core/go-scm/gitea` | Gitea SDK wrapper -- repos, issues, PRs, mirrors |
+| `agentci/` | `forge.lthn.ai/core/go-scm/agentci` | Clotho Protocol orchestration, agent config, security utilities |
+| `git/` | `forge.lthn.ai/core/go-scm/git` | Multi-repo parallel status, push, pull operations |
+| `jobrunner/` | `forge.lthn.ai/core/go-scm/jobrunner` | Signal polling, handler dispatch, JSONL audit journal |
+| `jobrunner/forgejo/` | `forge.lthn.ai/core/go-scm/jobrunner/forgejo` | Forgejo-specific job source (epic polling) |
+| `jobrunner/handlers/` | `forge.lthn.ai/core/go-scm/jobrunner/handlers` | Built-in handlers: dispatch, completion, merge, draft publish, fix commands, tick parent |
+| `collect/` | `forge.lthn.ai/core/go-scm/collect` | Data collection: GitHub issues, BitcoinTalk scraping, CoinGecko market data, IACR/arXiv papers |
+
+## Quick Start
+
+### Forgejo Client
+
+```go
+import "forge.lthn.ai/core/go-scm/forge"
+
+// Create from explicit credentials
+client, err := forge.New("https://forge.lthn.ai", "your-token")
+
+// Or resolve from config file / env vars / flags
+client, err := forge.NewFromConfig("", "")
+
+// Use the client
+user, err := client.GetCurrentUser()
+issues, err := client.ListIssues("core", "go-scm", forge.ListIssuesOpts{State: "open"})
+```
+
+### Gitea Client
+
+```go
+import "forge.lthn.ai/core/go-scm/gitea"
+
+client, err := gitea.New("https://git.lthn.ai", "your-token")
+repos, err := client.ListOrgRepos("Agentic")
+```
+
+### Multi-Repo Git Status
+
+```go
+import "forge.lthn.ai/core/go-scm/git"
+
+statuses := git.Status(ctx, git.StatusOptions{
+    Paths: []string{"/path/to/repo-a", "/path/to/repo-b"},
+    Names: map[string]string{"/path/to/repo-a": "repo-a"},
+})
+
+for _, s := range statuses {
+    if s.IsDirty() {
+        fmt.Printf("%s has %d modified, %d untracked files\n", s.Name, s.Modified, s.Untracked)
+    }
+}
+```
+
+### Job Runner
+
+```go
+import (
+    "forge.lthn.ai/core/go-scm/jobrunner"
+    forgejoSource "forge.lthn.ai/core/go-scm/jobrunner/forgejo"
+    "forge.lthn.ai/core/go-scm/jobrunner/handlers"
+)
+
+poller := jobrunner.NewPoller(jobrunner.PollerConfig{
+    Sources:      []jobrunner.JobSource{forgejoSource.New(cfg, forgeClient)},
+    Handlers:     []jobrunner.JobHandler{handlers.NewEnableAutoMergeHandler(forgeClient)},
+    Journal:      journal,
+    PollInterval: 60 * time.Second,
+})
+
+poller.Run(ctx) // Blocking poll-dispatch loop
+```
+
+## Dependencies
+
+| Dependency | Version | Purpose |
+|-----------|---------|---------|
+| `codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2` | v2.2.0 | Forgejo API SDK |
+| `code.gitea.io/sdk/gitea` | v0.23.2 | Gitea API SDK |
+| `forge.lthn.ai/core/go` | workspace | Core framework (config, logging, services) |
+| `golang.org/x/net` | v0.50.0 | HTML parsing for collect package |
+
+## Key Features
+
+- **Dual SCM support** -- identical patterns for Forgejo and Gitea with shared auth resolution
+- **Clotho Protocol** -- dual-run verification for critical repositories, configurable per-agent
+- **Epic-driven pipeline** -- polls epic issues, discovers child tasks, dispatches to agents via SSH
+- **Built-in handlers** -- auto-merge, draft publishing, review dismissal, fix commands, parent checkbox ticking
+- **Data collection** -- GitHub, BitcoinTalk, CoinGecko, IACR, arXiv with rate limiting and resume support
+- **Parallel git ops** -- concurrent status checks across dozens of repositories
+- **JSONL audit journal** -- date-partitioned, path-traversal-safe logging of all pipeline actions
+- **Security hardened** -- path sanitisation, shell argument escaping, strict SSH, token masking
+
+## Wiki Pages
+
+- [[Forge-Client]] -- Forgejo API wrapper and configuration
+- [[Gitea-Client]] -- Gitea API wrapper and configuration
+- [[AgentCI-and-Clotho]] -- Agent orchestration and the Clotho Protocol
+- [[Git-Operations]] -- Multi-repo git utilities and Core service integration
+- [[Job-Runner]] -- Signal polling, handler dispatch, and built-in handlers
+- [[Data-Collection]] -- GitHub, BitcoinTalk, market data, and paper collection