fix(ingest): parse docmark's SSE-framed response, not bare JSON

Found via a real live-cluster end-to-end test (POST /ingest-path with a real
.docx against the deployed ingestion + docmark): 'decode docmark response:
invalid character e looking for beginning of value'. docmark's Streamable-HTTP
transport frames every response as SSE (event: message\r\ndata: {...}\r\n\r\n,
Content-Type: text/event-stream) -- stateless_http=True removes the need for
an initialize handshake/session ID, it does NOT change the wire framing to
bare JSON. My original client + its own test mock both assumed bare JSON,
so the unit tests passed while the real call failed.

sseDataPayload() extracts the data: line before JSON-unmarshaling; falls back
to the raw body if no SSE framing is present (forward-compatible). Test mock
(docmark_test.go) now emits the SAME framing the live server actually sends,
confirmed by directly probing docmark's live response before writing the fix.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.context/system-prompt.txt

@@ -268,7 +268,7 @@ unconditionally on every host, every harness.
 
 ## Engineering Skills
 
-Shared engineering skills are available in `~/dev/.skills/`. Load at task start — not "on demand" but on schedule, before writing code. See `~/dev/.skills/SKILLS_INDEX.md` for the full list.
+Shared engineering skills live in the **`mathias/skills`** repo (`git.d-ma.be/mathias/skills`). Clone it to `~/dev/skills/` and run `SKILLS_CHECKOUT_DIR="$PWD" bash install.sh` there to wire every skill into your harnesses (Claude Code, Crush, Antigravity, Mistral Vibe) as native, on-demand skills. (Use `install.sh`, not `task install` — the latter is currently broken, skills#7.) Load at task start — not "on demand" but on schedule, before writing code. Browse `~/dev/skills/SKILLS_INDEX.md` for the full list.
 
 **Skill trigger table — load before starting, not after getting stuck:**
 

AGENTS.md

@@ -263,7 +263,7 @@ unconditionally on every host, every harness.
 
 ## Engineering Skills
 
-Shared engineering skills are available in `~/dev/.skills/`. Load at task start — not "on demand" but on schedule, before writing code. See `~/dev/.skills/SKILLS_INDEX.md` for the full list.
+Shared engineering skills live in the **`mathias/skills`** repo (`git.d-ma.be/mathias/skills`). Clone it to `~/dev/skills/` and run `SKILLS_CHECKOUT_DIR="$PWD" bash install.sh` there to wire every skill into your harnesses (Claude Code, Crush, Antigravity, Mistral Vibe) as native, on-demand skills. (Use `install.sh`, not `task install` — the latter is currently broken, skills#7.) Load at task start — not "on demand" but on schedule, before writing code. Browse `~/dev/skills/SKILLS_INDEX.md` for the full list.
 
 **Skill trigger table — load before starting, not after getting stuck:**
 

ingestion/cmd/server/main.go

@@ -34,12 +34,33 @@ import (
 	"github.com/mathiasbq/hyperguild/ingestion/internal/search"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/vectorstore"
 	"github.com/mathiasbq/hyperguild/ingestion/internal/watcher"
+	"github.com/mathiasbq/hyperguild/ingestion/internal/webhook"
+	"k8s.io/client-go/kubernetes"
+	"k8s.io/client-go/rest"
+	"k8s.io/client-go/tools/clientcmd"
 )
 
-// claudeSink converts each claudewatcher.Batch into one wiki note under
+// kubeClient builds an in-cluster Kubernetes client (falls back to
-// brain/wiki/claude-sessions/facts/. v1 emits one note per session
+// $KUBECONFIG for local dev/testing against a real cluster).
-// keyed by host + session id; classifier-driven hall routing is a
+func kubeClient() (kubernetes.Interface, error) {
-// follow-up (hyperguild#27 v2).
+	if cfg, err := rest.InClusterConfig(); err == nil {
+		return kubernetes.NewForConfig(cfg)
+	}
+	rules := clientcmd.NewDefaultClientConfigLoadingRules()
+	cc := clientcmd.NewNonInteractiveDeferredLoadingClientConfig(rules, &clientcmd.ConfigOverrides{})
+	cfg, err := cc.ClientConfig()
+	if err != nil {
+		return nil, fmt.Errorf("kube config (no in-cluster, no kubeconfig): %w", err)
+	}
+	return kubernetes.NewForConfig(cfg)
+}
+
+// claudeSink converts each claudewatcher.Batch into a raw session dump
+// under brain/archive/claude-sessions/<host>/. Deliberately NOT a wiki
+// note (api.WriteNote / brain/wiki/) — raw full transcripts out-ranked
+// curated ai-sessions summaries in BM25 (177,818 vs 45,335 on the same
+// query) and duplicated content already summarized elsewhere. Kept for
+// deep lookups, never indexed. See ai-sessions#10.
 type claudeSink struct {
 	brainDir string
 	logger   *slog.Logger
@@ -67,16 +88,14 @@ func (s *claudeSink) Ingest(ctx context.Context, b claudewatcher.Batch) error {
 		sb.WriteString("\n\n")
 	}
 	slug := "session-" + b.Host + "-" + b.SessionID
-	if _, err := api.WriteNote(s.brainDir, api.WriteNoteOptions{
+	dest := filepath.Join(s.brainDir, "archive", "claude-sessions", b.Host, slug+".md")
-		Filename: slug,
+	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
-		Wing:     "claude-sessions",
+		return fmt.Errorf("create claude-sessions archive dir: %w", err)
-		Hall:     "facts",
-		Type:     "source",
-		Domain:   b.ProjectID,
-		Content:  sb.String(),
-	}); err != nil {
-		return fmt.Errorf("write claude session note: %w", err)
 	}
+	if err := os.WriteFile(dest, []byte(sb.String()), 0o644); err != nil {
+		return fmt.Errorf("write claude session archive: %w", err)
+	}
+	s.logger.Debug("claude session archived (non-indexed)", "path", dest)
 	return nil
 }
 
@@ -352,6 +371,29 @@ func main() {
 		logger.Info("claudewatcher started",
 			"sessions_dir", claudeDir, "host", host, "interval", interval)
 	}
+
+	// Gitea push webhook -> on-demand brain-sync Job, instead of waiting up
+	// to 15 minutes for the next CronJob poll. Off by default (opt in via
+	// GITEA_WEBHOOK_SECRET) since it needs Job-create RBAC in the "brain"
+	// namespace that a fresh deploy won't have granted yet.
+	var webhookHandler *webhook.Handler
+	if webhookSecret := os.Getenv("GITEA_WEBHOOK_SECRET"); webhookSecret != "" {
+		kc, err := kubeClient()
+		if err != nil {
+			logger.Error("brain-sync webhook: kube client", "err", err)
+			os.Exit(1)
+		}
+		webhookHandler = &webhook.Handler{
+			Secret:      webhookSecret,
+			Clientset:   kc,
+			Namespace:   envOr("BRAIN_SYNC_NAMESPACE", "brain"),
+			CronJobName: envOr("BRAIN_SYNC_CRONJOB", "brain-sync"),
+			WatchRepo:   envOr("BRAIN_SYNC_WATCH_REPO", "mathias/brain"),
+			Logger:      logger,
+		}
+		logger.Info("brain-sync webhook enabled", "namespace", webhookHandler.Namespace, "cronjob", webhookHandler.CronJobName)
+	}
+
 	if vectorStore != nil {
 		embedSyncInterval := envInt("BRAIN_EMBED_SYNC_INTERVAL", 300)
 		vectorstore.StartSync(ctx, brainDir, vectorStore,
@@ -373,6 +415,9 @@ func main() {
 	mux.HandleFunc("POST /promote", h.Promote)
 	mux.HandleFunc("POST /backfill-embeddings", h.BackfillEmbeddings)
 	mux.HandleFunc("GET /pass-rate", h.PassRate)
+	if webhookHandler != nil {
+		mux.Handle("POST /webhooks/brain-sync", webhookHandler)
+	}
 	jwtValidator, err := chassisauth.NewJWTValidator(ctx, os.Getenv("DEX_ISSUER_URL"), os.Getenv("MCP_AUDIENCE"))
 	if err != nil {
 		logger.Error("build jwt validator", "err", err)

ingestion/cmd/server/main_test.go

@@ -0,0 +1,38 @@
+// ingestion/cmd/server/main_test.go
+package main
+
+import (
+	"context"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/claudewatcher"
+)
+
+func TestClaudeSink_IngestWritesToNonIndexedArchiveNotWiki(t *testing.T) {
+	dir := t.TempDir()
+	sink := &claudeSink{brainDir: dir, logger: slog.New(slog.NewTextHandler(os.Stderr, nil))}
+
+	err := sink.Ingest(context.Background(), claudewatcher.Batch{
+		Host:      "koala",
+		FilePath:  "/host-home-claude/projects/-home-mathias-dev/abc.jsonl",
+		SessionID: "abc",
+		ProjectID: "-home-mathias-dev",
+		Turns: []claudewatcher.Turn{
+			{Type: "assistant", Content: "did a thing"},
+		},
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, "archive", "claude-sessions", "koala", "session-koala-abc.md"))
+	require.NoError(t, err, "raw session dump must land in the non-indexed archive")
+	assert.Contains(t, string(got), "did a thing")
+
+	_, err = os.Stat(filepath.Join(dir, "wiki", "claude-sessions"))
+	assert.True(t, os.IsNotExist(err), "raw transcripts must never land under wiki/ (ai-sessions#10 — BM25 pollution)")
+}

ingestion/go.mod

@@ -2,17 +2,57 @@ module github.com/mathiasbq/hyperguild/ingestion
 
 go 1.26.1
 
-require github.com/stretchr/testify v1.11.1
+require (
+	github.com/stretchr/testify v1.11.1
+	k8s.io/api v0.31.3
+	k8s.io/apimachinery v0.31.3
+	k8s.io/client-go v0.31.3
+)
 
 require (
-	github.com/kr/text v0.2.0 // indirect
+	github.com/emicklei/go-restful/v3 v3.11.0 // indirect
+	github.com/fxamacker/cbor/v2 v2.7.0 // indirect
+	github.com/go-logr/logr v1.4.2 // indirect
+	github.com/go-openapi/jsonpointer v0.19.6 // indirect
+	github.com/go-openapi/jsonreference v0.20.2 // indirect
+	github.com/go-openapi/swag v0.22.4 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/protobuf v1.5.4 // indirect
+	github.com/google/gnostic-models v0.6.8 // indirect
+	github.com/google/go-cmp v0.6.0 // indirect
+	github.com/google/gofuzz v1.2.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/imdario/mergo v0.3.6 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/lestrrat-go/jwx/v2 v2.1.6 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
 	github.com/rogpeppe/go-internal v1.15.0 // indirect
+	github.com/spf13/pflag v1.0.5 // indirect
+	github.com/x448/float16 v0.8.4 // indirect
+	golang.org/x/net v0.26.0 // indirect
+	golang.org/x/oauth2 v0.21.0 // indirect
+	golang.org/x/term v0.28.0 // indirect
+	golang.org/x/time v0.3.0 // indirect
+	google.golang.org/protobuf v1.34.2 // indirect
+	gopkg.in/evanphx/json-patch.v4 v4.12.0 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	k8s.io/klog/v2 v2.130.1 // indirect
+	k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340 // indirect
+	k8s.io/utils v0.0.0-20240711033017-18e509b52bc8 // indirect
+	sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
+	sigs.k8s.io/structured-merge-diff/v4 v4.4.1 // indirect
+	sigs.k8s.io/yaml v1.4.0 // indirect
 )
 
 require (
 	git.d-ma.be/mathias/mcp-chassis v0.2.0
-	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 // indirect
 	github.com/goccy/go-json v0.10.3 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
@@ -24,7 +64,7 @@ require (
 	github.com/lestrrat-go/httprc v1.0.6 // indirect
 	github.com/lestrrat-go/iter v1.0.2 // indirect
 	github.com/lestrrat-go/option v1.0.1 // indirect
-	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/segmentio/asm v1.2.0 // indirect
 	golang.org/x/crypto v0.32.0 // indirect
 	golang.org/x/sync v0.17.0 // indirect

ingestion/go.sum

@@ -2,12 +2,46 @@ git.d-ma.be/mathias/mcp-chassis v0.2.0 h1:6fLmb7xqRa2nNVWsHaUbbfbArgDXJw/gDhb09c
 git.d-ma.be/mathias/mcp-chassis v0.2.0/go.mod h1:Ks7EK2UnGAN0H3rJjKUxUagX8/ZBdtLrOlcUbv0RwH8=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 h1:NMZiJj8QnKe1LgsbDayM4UoHwbvwDRwnI3hwNaAHRnc=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
+github.com/emicklei/go-restful/v3 v3.11.0 h1:rAQeMHw1c7zTmncogyy8VvRZwtkmkZ4FxERmMY4rD+g=
+github.com/emicklei/go-restful/v3 v3.11.0/go.mod h1:6n3XBCmQQb25CM2LCACGz8ukIrRry+4bhvbpWn3mrbc=
+github.com/fxamacker/cbor/v2 v2.7.0 h1:iM5WgngdRBanHcxugY4JySA0nk1wZorNOpTgCMedv5E=
+github.com/fxamacker/cbor/v2 v2.7.0/go.mod h1:pxXPTn3joSm21Gbwsv0w9OSA2y1HFR9qXEeXQVeNoDQ=
+github.com/go-logr/logr v1.4.2 h1:6pFjapn8bFcIbiKo3XT4j/BhANplGihG6tvd+8rYgrY=
+github.com/go-logr/logr v1.4.2/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-openapi/jsonpointer v0.19.6 h1:eCs3fxoIi3Wh6vtgmLTOjdhSpiqphQ+DaPn38N2ZdrE=
+github.com/go-openapi/jsonpointer v0.19.6/go.mod h1:osyAmYz/mB/C3I+WsTTSgw1ONzaLJoLCyoi6/zppojs=
+github.com/go-openapi/jsonreference v0.20.2 h1:3sVjiK66+uXK/6oQ8xgcRKcFgQ5KXa2KvnJRumpMGbE=
+github.com/go-openapi/jsonreference v0.20.2/go.mod h1:Bl1zwGIM8/wsvqjsOQLJ/SH+En5Ap4rVB5KVcIDZG2k=
+github.com/go-openapi/swag v0.22.3/go.mod h1:UzaqsxGiab7freDnrUUra0MwWfN/q7tE4j+VcZ0yl14=
+github.com/go-openapi/swag v0.22.4 h1:QLMzNJnMGPRNDCbySlcj1x01tzU8/9LTTL9hZZZogBU=
+github.com/go-openapi/swag v0.22.4/go.mod h1:UzaqsxGiab7freDnrUUra0MwWfN/q7tE4j+VcZ0yl14=
+github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI=
+github.com/go-task/slim-sprig/v3 v3.0.0/go.mod h1:W848ghGpv3Qj3dhTPRyJypKRiqCdHZiAzKg9hl15HA8=
 github.com/goccy/go-json v0.10.3 h1:KZ5WoDbxAIgm2HNbYckL0se1fHD6rz5j4ywS6ebzDqA=
 github.com/goccy/go-json v0.10.3/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
+github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
+github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/gnostic-models v0.6.8 h1:yo/ABAfM5IMRsS1VnXjTBvUb61tFIHozhlYvRgGre9I=
+github.com/google/gnostic-models v0.6.8/go.mod h1:5n7qKqH0f5wFt+aWF8CW6pZLLNOfYuF5OpfBSENuI8U=
+github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/gofuzz v1.2.0 h1:xRy4A+RhZaiKjJ1bPfwQ8sedCA+YS2YcCHW6ec7JMi0=
+github.com/google/gofuzz v1.2.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/pprof v0.0.0-20240525223248-4bfdf5a9a2af h1:kmjWCqn2qkEml422C2Rrd27c3VGxi6a/6HNq8QmHRKM=
+github.com/google/pprof v0.0.0-20240525223248-4bfdf5a9a2af/go.mod h1:K1liHPHnj73Fdn/EKuT8nrFqBihUSKXoLYU0BuatOYo=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/imdario/mergo v0.3.6 h1:xTNEAn+kxVO7dTZGu0CegyqKZmoWFI0rF8UxjlB2d28=
+github.com/imdario/mergo v0.3.6/go.mod h1:2EnlNZ0deacrJVfApfmtdGgDfMuh/nq6Ok1EcJh5FfA=
 github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
 github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
@@ -16,8 +50,17 @@ github.com/jackc/pgx/v5 v5.9.2 h1:3ZhOzMWnR4yJ+RW1XImIPsD1aNSz4T4fyP7zlQb56hw=
 github.com/jackc/pgx/v5 v5.9.2/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
-github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
+github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
-github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
+github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
+github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
+github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/lestrrat-go/blackmagic v1.0.3 h1:94HXkVLxkZO9vJI/w2u1T0DAoprShFd13xtnSINtDWs=
@@ -32,30 +75,118 @@ github.com/lestrrat-go/jwx/v2 v2.1.6 h1:hxM1gfDILk/l5ylers6BX/Eq1m/pnxe9NBwW6lVf
 github.com/lestrrat-go/jwx/v2 v2.1.6/go.mod h1:Y722kU5r/8mV7fYDifjug0r8FK8mZdw0K0GpJw/l8pU=
 github.com/lestrrat-go/option v1.0.1 h1:oAzP2fvZGQKWkvHa1/SAcFolBEca1oN+mQ7eooNBEYU=
 github.com/lestrrat-go/option v1.0.1/go.mod h1:5ZHFbivi4xwXxhxY9XHDe2FHo6/Z7WWmtT7T5nBBp3I=
-github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
+github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
+github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
+github.com/onsi/ginkgo/v2 v2.19.0 h1:9Cnnf7UHo57Hy3k6/m5k3dRfGTMXGvxhHFvkDTCTpvA=
+github.com/onsi/ginkgo/v2 v2.19.0/go.mod h1:rlwLi9PilAFJ8jCg9UE1QP6VBpd6/xj3SRC0d6TU0To=
+github.com/onsi/gomega v1.19.0 h1:4ieX6qQjPP/BfC3mpsAtIGGlxTWPeA3Inl/7DtXw1tw=
+github.com/onsi/gomega v1.19.0/go.mod h1:LY+I3pBVzYsTBU1AnDwOSxaYi9WoWiqgwooUqq9yPro=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rogpeppe/go-internal v1.15.0 h1:D0RCU5rMAp+SpgkiNdrjfJ+LX4J1M32V2NeCY7EJ6hc=
 github.com/rogpeppe/go-internal v1.15.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs=
 github.com/segmentio/asm v1.2.0 h1:9BQrFxC+YOHJlTlHGkTrFWf59nbL3XnCoFLTwDCI7ys=
 github.com/segmentio/asm v1.2.0/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
+github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
+github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
+github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
+github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
+golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
 golang.org/x/crypto v0.32.0 h1:euUpcYgM8WcP71gNpTqQCn6rC2t6ULUPiOzfWaXVVfc=
 golang.org/x/crypto v0.32.0/go.mod h1:ZnnJkOaASj8g0AjIduWNlq2NRxL0PlBrbKVyZ6V/Ugc=
+golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
+golang.org/x/net v0.26.0 h1:soB7SVo0PWrY4vPW/+ay0jKDNScG2X9wFeYlXIvJsOQ=
+golang.org/x/net v0.26.0/go.mod h1:5YKkiSynbBIh3p6iOc/vibscux0x38BZDkn8sCUPxHE=
+golang.org/x/oauth2 v0.21.0 h1:tsimM75w1tF/uws5rbeHzIWxEqElMehnc+iW793zsZs=
+golang.org/x/oauth2 v0.21.0/go.mod h1:XYTD2NtWslqkgxebSiOHnXEap4TF09sJSc7H1sXbhtI=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
 golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
 golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/term v0.28.0 h1:/Ts8HFuMR2E6IP/jlo7QVLZHggjKQbhu/7H0LJFr3Gg=
+golang.org/x/term v0.28.0/go.mod h1:Sw/lC2IAUZ92udQNf3WodGtn4k/XoLyZoh8v/8uiwek=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
 golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
+golang.org/x/time v0.3.0 h1:rg5rLMjNzMS1RkNLzCG38eapWhnYLFYXDXj2gOlr8j4=
+golang.org/x/time v0.3.0/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
+golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
+golang.org/x/tools v0.36.0 h1:kWS0uv/zsvHEle1LbV5LE8QujrxB3wfQyxHfhOk0Qkg=
+golang.org/x/tools v0.36.0/go.mod h1:WBDiHKJK8YgLHlcQPYQzNCkUxUypCaa5ZegCVutKm+s=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/protobuf v1.34.2 h1:6xV6lTsCfpGD21XK49h7MhtcApnLqkfYgPcdHftf6hg=
+google.golang.org/protobuf v1.34.2/go.mod h1:qYOHts0dSfpeUzUFpOMr/WGzszTmLH+DiWniOlNbLDw=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/evanphx/json-patch.v4 v4.12.0 h1:n6jtcsulIzXPJaxegRbvFNNrZDjbij7ny3gmSPG+6V4=
+gopkg.in/evanphx/json-patch.v4 v4.12.0/go.mod h1:p8EYWUEYMpynmqDbY58zCKCFZw8pRWMG4EsWvDvM72M=
+gopkg.in/inf.v0 v0.9.1 h1:73M5CoZyi3ZLMOyDlQh031Cx6N9NDJ2Vvfl76EDAgDc=
+gopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=
+gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+k8s.io/api v0.31.3 h1:umzm5o8lFbdN/hIXbrK9oRpOproJO62CV1zqxXrLgk8=
+k8s.io/api v0.31.3/go.mod h1:UJrkIp9pnMOI9K2nlL6vwpxRzzEX5sWgn8kGQe92kCE=
+k8s.io/apimachinery v0.31.3 h1:6l0WhcYgasZ/wk9ktLq5vLaoXJJr5ts6lkaQzgeYPq4=
+k8s.io/apimachinery v0.31.3/go.mod h1:rsPdaZJfTfLsNJSQzNHQvYoTmxhoOEofxtOsF3rtsMo=
+k8s.io/client-go v0.31.3 h1:CAlZuM+PH2cm+86LOBemaJI/lQ5linJ6UFxKX/SoG+4=
+k8s.io/client-go v0.31.3/go.mod h1:2CgjPUTpv3fE5dNygAr2NcM8nhHzXvxB8KL5gYc3kJs=
+k8s.io/klog/v2 v2.130.1 h1:n9Xl7H1Xvksem4KFG4PYbdQCQxqc/tTUyrgXaOhHSzk=
+k8s.io/klog/v2 v2.130.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE=
+k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340 h1:BZqlfIlq5YbRMFko6/PM7FjZpUb45WallggurYhKGag=
+k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340/go.mod h1:yD4MZYeKMBwQKVht279WycxKyM84kkAx2DPrTXaeb98=
+k8s.io/utils v0.0.0-20240711033017-18e509b52bc8 h1:pUdcCO1Lk/tbT5ztQWOBi5HBgbBP1J8+AsQnQCKsi8A=
+k8s.io/utils v0.0.0-20240711033017-18e509b52bc8/go.mod h1:OLgZIPagt7ERELqWJFomSt595RzquPNLL48iOWgYOg0=
+sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd h1:EDPBXCAspyGV4jQlpZSudPeMmr1bNJefnuqLsRAsHZo=
+sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd/go.mod h1:B8JuhiUyNFVKdsE8h686QcCxMaH6HrOAZj4vswFpcB0=
+sigs.k8s.io/structured-merge-diff/v4 v4.4.1 h1:150L+0vs/8DA78h1u02ooW1/fFq/Lwr+sGiqlzvrtq4=
+sigs.k8s.io/structured-merge-diff/v4 v4.4.1/go.mod h1:N8hJocpFajUSSeSJ9bOZ77VzejKZaXsTtZo4/u7Io08=
+sigs.k8s.io/yaml v1.4.0 h1:Mk1wCc2gy/F0THH0TAp1QYyJNzRm2KCLy3o5ASXVI5E=
+sigs.k8s.io/yaml v1.4.0/go.mod h1:Ejl7/uTz7PSA4eKMyQCUTnhZYNmLIl+5c2lQPGR2BPY=

ingestion/internal/api/handler.go

@@ -57,6 +57,7 @@ type writeRequest struct {
 	Domain     string `json:"domain,omitempty"`
 	Wing       string `json:"wing,omitempty"`
 	Hall       string `json:"hall,omitempty"`
+	SourceType string `json:"source_type,omitempty"` // "external" opts a hall=facts entry out of the internal default
 }
 
 type ingestRequest struct {
@@ -121,6 +122,7 @@ type WriteNoteOptions struct {
 	Domain     string
 	Wing       string
 	Hall       string
+	SourceType string // "internal" marks a first-party observation (e.g. claudewatcher) that needs no external citation
 }
 
 // WriteNote writes a markdown note into the brain. Returns the path
@@ -165,6 +167,17 @@ func writeHallNote(brainDir string, opts WriteNoteOptions) (string, error) {
 	if opts.Domain != "" {
 		fmt.Fprintf(&fm, "domain: %s\n", opts.Domain)
 	}
+	sourceType := opts.SourceType
+	if sourceType == "" && opts.Hall == "facts" {
+		// Most hall=facts entries are first-party (an eval/benchmark the
+		// writer ran itself), not external claims — default to internal and
+		// require an explicit source_type: external opt-out for the rare
+		// citation-needing entry (brain-gardener#7).
+		sourceType = "internal"
+	}
+	if sourceType != "" {
+		fmt.Fprintf(&fm, "source_type: %s\n", sourceType)
+	}
 	fm.WriteString("---\n")
 
 	if err := os.WriteFile(dest, []byte(fm.String()+opts.Content), 0o644); err != nil {
@@ -332,11 +345,19 @@ func (h *Handler) Ingest(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, ingestResponse{Pages: pages, Warnings: warnings})
 }
 
-// supportedExtensions lists file extensions that IngestPath will process.
+// isSupportedExtension reports whether IngestPath will process ext.
-var supportedExtensions = map[string]bool{
+// .docx/.xlsx/.pptx/.png/.jpg/.jpeg require docmark (ADR-0013) and are only
-	".md":  true,
+// supported when DOCMARK_URL is configured — checked per-call (not cached at
-	".txt": true,
+// package init) so it reflects the environment at request time.
-	".pdf": true,
+func isSupportedExtension(ext string) bool {
+	switch ext {
+	case ".md", ".txt", ".pdf":
+		return true
+	case ".docx", ".xlsx", ".pptx", ".png", ".jpg", ".jpeg":
+		return os.Getenv("DOCMARK_URL") != ""
+	default:
+		return false
+	}
 }
 
 // IngestPath handles POST /ingest-path — ingest a file or directory.
@@ -369,7 +390,7 @@ func (h *Handler) IngestPath(w http.ResponseWriter, r *http.Request) {
 				return nil
 			}
 			ext := strings.ToLower(filepath.Ext(path))
-			if !supportedExtensions[ext] {
+			if !isSupportedExtension(ext) {
 				return nil
 			}
 			content, readErr := extract.Text(path)
@@ -397,7 +418,7 @@ func (h *Handler) IngestPath(w http.ResponseWriter, r *http.Request) {
 		}
 	} else {
 		ext := strings.ToLower(filepath.Ext(req.Path))
-		if !supportedExtensions[ext] {
+		if !isSupportedExtension(ext) {
 			writeError(w, http.StatusBadRequest, fmt.Sprintf("unsupported file extension: %s", ext))
 			return
 		}

ingestion/internal/api/handler_test.go

@@ -118,6 +118,74 @@ func TestWrite_IncludesFrontmatterWhenTypeProvided(t *testing.T) {
 	assert.Contains(t, string(content), "Some learning.")
 }
 
+func TestWriteNote_HallRouteIncludesSourceTypeWhenSet(t *testing.T) {
+	dir := t.TempDir()
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content:    "# Claude session abc (koala)\n\nBody.\n",
+		Filename:   "session-koala-abc",
+		Wing:       "claude-sessions",
+		Hall:       "facts",
+		Type:       "source",
+		SourceType: "internal",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "source_type: internal")
+	assert.Contains(t, string(got), "wing: claude-sessions")
+}
+
+func TestWriteNote_HallFactsDefaultsSourceTypeInternalWhenUnset(t *testing.T) {
+	dir := t.TempDir()
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content: "manually captured fact.\n",
+		Wing:    "agentsquad",
+		Hall:    "facts",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	// Most hall=facts entries are first-party (an eval/benchmark the agent ran
+	// itself), not external claims — default to internal, require explicit
+	// opt-out for the rare case that does need a citation (brain-gardener#7).
+	assert.Contains(t, string(got), "source_type: internal")
+}
+
+func TestWriteNote_HallFactsPreservesExplicitExternalSourceType(t *testing.T) {
+	dir := t.TempDir()
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content:    "vendor pricing claim, needs a citation.\n",
+		Wing:       "agentsquad",
+		Hall:       "facts",
+		SourceType: "external",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.Contains(t, string(got), "source_type: external")
+}
+
+func TestWriteNote_HallRouteOmitsSourceTypeForNonFactsHalls(t *testing.T) {
+	dir := t.TempDir()
+
+	rel, err := api.WriteNote(dir, api.WriteNoteOptions{
+		Content: "a decision record.\n",
+		Wing:    "agentsquad",
+		Hall:    "decisions",
+	})
+	require.NoError(t, err)
+
+	got, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(rel)))
+	require.NoError(t, err)
+	assert.NotContains(t, string(got), "source_type")
+}
+
 func TestWrite_GeneratesFilenameIfAbsent(t *testing.T) {
 	dir, h := setup(t)
 	body, _ := json.Marshal(map[string]any{"content": "auto name"})

ingestion/internal/api/ingestpath_docmark_test.go

@@ -0,0 +1,61 @@
+// ingestion/internal/api/ingestpath_docmark_test.go
+package api_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestIngestPath_DocxUnsupportedWhenDocmarkNotConfigured(t *testing.T) {
+	t.Setenv("DOCMARK_URL", "")
+	_, h := setup(t)
+
+	dir := t.TempDir()
+	f := filepath.Join(dir, "doc.docx")
+	require.NoError(t, os.WriteFile(f, []byte("fake docx"), 0o644))
+
+	body, _ := json.Marshal(map[string]any{"path": f, "source": "test-doc", "dry_run": true})
+	req := httptest.NewRequest(http.MethodPost, "/ingest-path", bytes.NewReader(body))
+	rec := httptest.NewRecorder()
+
+	h.IngestPath(rec, req)
+
+	assert.Equal(t, http.StatusBadRequest, rec.Code, rec.Body.String())
+}
+
+func TestIngestPath_DocxSupportedWhenDocmarkConfigured(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"# Converted Doc"}]}}`))
+	}))
+	defer srv.Close()
+	t.Setenv("DOCMARK_URL", srv.URL+"/mcp")
+	t.Setenv("DOCMARK_BEARER_TOKEN", "tok")
+
+	_, h := setup(t)
+
+	dir := t.TempDir()
+	f := filepath.Join(dir, "doc.docx")
+	require.NoError(t, os.WriteFile(f, []byte("fake docx"), 0o644))
+
+	body, _ := json.Marshal(map[string]any{"path": f, "source": "test-doc", "dry_run": true})
+	req := httptest.NewRequest(http.MethodPost, "/ingest-path", bytes.NewReader(body))
+	rec := httptest.NewRecorder()
+
+	h.IngestPath(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	var resp map[string]any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	pages, ok := resp["pages"].([]any)
+	require.True(t, ok)
+	assert.NotEmpty(t, pages)
+}

ingestion/internal/extract/docmark.go

@@ -0,0 +1,148 @@
+// ingestion/internal/extract/docmark.go
+package extract
+
+import (
+	"bytes"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"time"
+)
+
+// docmarkRequest is a JSON-RPC 2.0 tools/call request for docmark's
+// convert_to_markdown tool.
+type docmarkRequest struct {
+	JSONRPC string `json:"jsonrpc"`
+	ID      int    `json:"id"`
+	Method  string `json:"method"`
+	Params  struct {
+		Name      string `json:"name"`
+		Arguments struct {
+			ContentBase64 string `json:"content_base64"`
+			Filename      string `json:"filename"`
+		} `json:"arguments"`
+	} `json:"params"`
+}
+
+type docmarkResponse struct {
+	Result *struct {
+		Content []struct {
+			Type string `json:"type"`
+			Text string `json:"text"`
+		} `json:"content"`
+		IsError bool `json:"isError"`
+	} `json:"result"`
+	Error *struct {
+		Message string `json:"message"`
+	} `json:"error"`
+}
+
+// extractViaDocmark converts path (PDF/DOCX/XLSX/PPTX/image) to Markdown by
+// calling the docmark MCP server with a single self-contained tools/call
+// request (docmark runs stateless_http -- no initialize handshake or session
+// ID needed). DOCMARK_URL must be set (e.g.
+// http://docmark.docmark.svc.cluster.local:3001/mcp); DOCMARK_BEARER_TOKEN
+// is docmark's static bearer (network is docmark's primary auth boundary,
+// this is defense-in-depth — ADR-0013).
+func extractViaDocmark(path string) (string, error) {
+	url := os.Getenv("DOCMARK_URL")
+	if url == "" {
+		return "", fmt.Errorf("extractViaDocmark: DOCMARK_URL is not set")
+	}
+
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return "", fmt.Errorf("read %s: %w", path, err)
+	}
+
+	var reqBody docmarkRequest
+	reqBody.JSONRPC = "2.0"
+	reqBody.ID = 1
+	reqBody.Method = "tools/call"
+	reqBody.Params.Name = "convert_to_markdown"
+	reqBody.Params.Arguments.ContentBase64 = base64.StdEncoding.EncodeToString(raw)
+	reqBody.Params.Arguments.Filename = fileBase(path)
+
+	payload, err := json.Marshal(reqBody)
+	if err != nil {
+		return "", fmt.Errorf("marshal docmark request: %w", err)
+	}
+
+	httpReq, err := http.NewRequest(http.MethodPost, url, bytes.NewReader(payload))
+	if err != nil {
+		return "", fmt.Errorf("build docmark request: %w", err)
+	}
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Accept", "application/json, text/event-stream")
+	if tok := os.Getenv("DOCMARK_BEARER_TOKEN"); tok != "" {
+		httpReq.Header.Set("Authorization", "Bearer "+tok)
+	}
+
+	client := &http.Client{Timeout: 60 * time.Second}
+	resp, err := client.Do(httpReq)
+	if err != nil {
+		return "", fmt.Errorf("call docmark: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("read docmark response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("docmark: HTTP %d: %s", resp.StatusCode, string(body))
+	}
+
+	jsonBody := body
+	if data := sseDataPayload(body); data != nil {
+		jsonBody = data
+	}
+
+	var out docmarkResponse
+	if err := json.Unmarshal(jsonBody, &out); err != nil {
+		return "", fmt.Errorf("decode docmark response: %w", err)
+	}
+	if out.Error != nil {
+		return "", fmt.Errorf("docmark: %s", out.Error.Message)
+	}
+	if out.Result == nil || len(out.Result.Content) == 0 {
+		return "", fmt.Errorf("docmark: empty response")
+	}
+	text := out.Result.Content[0].Text
+	if out.Result.IsError {
+		return "", fmt.Errorf("docmark: %s", text)
+	}
+	return text, nil
+}
+
+// sseDataPayload extracts the JSON payload from an SSE-framed response body
+// ("event: message\r\ndata: {...}\r\n\r\n"). docmark's Streamable-HTTP
+// transport frames every response this way (Content-Type: text/event-stream)
+// regardless of stateless_http — that flag removes the session/initialize
+// requirement, not the SSE wire framing. Returns nil if body isn't SSE-framed
+// (e.g. a plain-JSON response, kept as a fallback for forward-compatibility).
+func sseDataPayload(body []byte) []byte {
+	const prefix = "data: "
+	for _, line := range bytes.Split(body, []byte("\n")) {
+		line = bytes.TrimRight(line, "\r")
+		if bytes.HasPrefix(line, []byte(prefix)) {
+			return bytes.TrimPrefix(line, []byte(prefix))
+		}
+	}
+	return nil
+}
+
+// fileBase returns the final path segment (like filepath.Base, kept local to
+// avoid importing path/filepath just for this one call).
+func fileBase(path string) string {
+	for i := len(path) - 1; i >= 0; i-- {
+		if path[i] == '/' || path[i] == '\\' {
+			return path[i+1:]
+		}
+	}
+	return path
+}

ingestion/internal/extract/docmark_test.go

@@ -0,0 +1,189 @@
+// ingestion/internal/extract/docmark_test.go
+package extract
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// mcpToolResult mirrors the shape of docmark's JSON-RPC tools/call response.
+type mcpToolResult struct {
+	JSONRPC string `json:"jsonrpc"`
+	ID      int    `json:"id"`
+	Result  *struct {
+		Content []struct {
+			Type string `json:"type"`
+			Text string `json:"text"`
+		} `json:"content"`
+		IsError bool `json:"isError"`
+	} `json:"result,omitempty"`
+	Error *struct {
+		Message string `json:"message"`
+	} `json:"error,omitempty"`
+}
+
+// writeMCPResponse mirrors docmark's REAL response framing (empirically
+// confirmed against the live server): Content-Type: text/event-stream,
+// body is SSE-framed ("event: message\r\ndata: {...}\r\n\r\n"), not bare
+// JSON -- inherent to MCP Streamable-HTTP, independent of stateless_http.
+func writeMCPResponse(w http.ResponseWriter, body mcpToolResult) {
+	payload, _ := json.Marshal(body)
+	w.Header().Set("Content-Type", "text/event-stream")
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte("event: message\r\ndata: "))
+	_, _ = w.Write(payload)
+	_, _ = w.Write([]byte("\r\n\r\n"))
+}
+
+func TestExtractViaDocmark_Success(t *testing.T) {
+	var gotAuth, gotAccept string
+	var gotBody map[string]any
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotAuth = r.Header.Get("Authorization")
+		gotAccept = r.Header.Get("Accept")
+		b, _ := io.ReadAll(r.Body)
+		_ = json.Unmarshal(b, &gotBody)
+		writeMCPResponse(w, mcpToolResult{
+			JSONRPC: "2.0", ID: 1,
+			Result: &struct {
+				Content []struct {
+					Type string `json:"type"`
+					Text string `json:"text"`
+				} `json:"content"`
+				IsError bool `json:"isError"`
+			}{
+				Content: []struct {
+					Type string `json:"type"`
+					Text string `json:"text"`
+				}{{Type: "text", Text: "# Converted\n\nhello"}},
+			},
+		})
+	}))
+	defer srv.Close()
+
+	t.Setenv("DOCMARK_URL", srv.URL+"/mcp")
+	t.Setenv("DOCMARK_BEARER_TOKEN", "test-token-123")
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "doc.docx")
+	require.NoError(t, os.WriteFile(path, []byte("fake docx bytes"), 0o644))
+
+	got, err := extractViaDocmark(path)
+	require.NoError(t, err)
+	assert.Equal(t, "# Converted\n\nhello", got)
+	assert.Equal(t, "Bearer test-token-123", gotAuth)
+	assert.Contains(t, gotAccept, "application/json")
+	params, _ := gotBody["params"].(map[string]any)
+	require.NotNil(t, params)
+	assert.Equal(t, "convert_to_markdown", params["name"])
+	args, _ := params["arguments"].(map[string]any)
+	require.NotNil(t, args)
+	assert.Equal(t, "doc.docx", args["filename"])
+	assert.NotEmpty(t, args["content_base64"])
+}
+
+func TestExtractViaDocmark_NotConfigured(t *testing.T) {
+	t.Setenv("DOCMARK_URL", "")
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "doc.docx")
+	require.NoError(t, os.WriteFile(path, []byte("x"), 0o644))
+
+	_, err := extractViaDocmark(path)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "DOCMARK_URL")
+}
+
+func TestExtractViaDocmark_ToolErrorSurfacesMessage(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		writeMCPResponse(w, mcpToolResult{
+			JSONRPC: "2.0", ID: 1,
+			Result: &struct {
+				Content []struct {
+					Type string `json:"type"`
+					Text string `json:"text"`
+				} `json:"content"`
+				IsError bool `json:"isError"`
+			}{
+				Content: []struct {
+					Type string `json:"type"`
+					Text string `json:"text"`
+				}{{Type: "text", Text: "unsupported format for 'doc.docx'"}},
+				IsError: true,
+			},
+		})
+	}))
+	defer srv.Close()
+
+	t.Setenv("DOCMARK_URL", srv.URL+"/mcp")
+	t.Setenv("DOCMARK_BEARER_TOKEN", "tok")
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "doc.docx")
+	require.NoError(t, os.WriteFile(path, []byte("x"), 0o644))
+
+	_, err := extractViaDocmark(path)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "unsupported format")
+}
+
+func TestExtractViaDocmark_HTTPErrorSurfaces(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+		_, _ = w.Write([]byte("unauthorized"))
+	}))
+	defer srv.Close()
+
+	t.Setenv("DOCMARK_URL", srv.URL+"/mcp")
+	t.Setenv("DOCMARK_BEARER_TOKEN", "wrong")
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "doc.docx")
+	require.NoError(t, os.WriteFile(path, []byte("x"), 0o644))
+
+	_, err := extractViaDocmark(path)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "401")
+}
+
+func TestText_RoutesDocxXlsxPptxImagesToDocmark(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		writeMCPResponse(w, mcpToolResult{
+			JSONRPC: "2.0", ID: 1,
+			Result: &struct {
+				Content []struct {
+					Type string `json:"type"`
+					Text string `json:"text"`
+				} `json:"content"`
+				IsError bool `json:"isError"`
+			}{
+				Content: []struct {
+					Type string `json:"type"`
+					Text string `json:"text"`
+				}{{Type: "text", Text: "converted"}},
+			},
+		})
+	}))
+	defer srv.Close()
+	t.Setenv("DOCMARK_URL", srv.URL+"/mcp")
+	t.Setenv("DOCMARK_BEARER_TOKEN", "tok")
+
+	for _, ext := range []string{".docx", ".xlsx", ".pptx", ".png", ".jpg", ".jpeg"} {
+		t.Run(ext, func(t *testing.T) {
+			dir := t.TempDir()
+			path := filepath.Join(dir, "f"+ext)
+			require.NoError(t, os.WriteFile(path, []byte("x"), 0o644))
+			got, err := Text(path)
+			require.NoError(t, err)
+			assert.Equal(t, "converted", got)
+		})
+	}
+}

ingestion/internal/extract/extract.go

@@ -8,7 +8,9 @@ import (
 )
 
 // Text reads the file at path and returns its plain-text content.
-// Supported extensions: .md, .txt (passthrough), .pdf (via pdftotext).
+// Supported extensions: .md, .txt (passthrough), .pdf (via pdftotext),
+// .docx/.xlsx/.pptx/.png/.jpg/.jpeg (via docmark, ADR-0013 -- requires
+// DOCMARK_URL to be set; see docmark.go).
 func Text(path string) (string, error) {
 	ext := strings.ToLower(fileExt(path))
 	switch ext {
@@ -20,6 +22,8 @@ func Text(path string) (string, error) {
 		return string(b), nil
 	case ".pdf":
 		return extractPDF(path)
+	case ".docx", ".xlsx", ".pptx", ".png", ".jpg", ".jpeg":
+		return extractViaDocmark(path)
 	default:
 		return "", fmt.Errorf("unsupported file extension: %s", ext)
 	}

ingestion/internal/webhook/webhook.go

@@ -0,0 +1,109 @@
+// Package webhook triggers an on-demand brain-sync Job when Gitea pushes to
+// mathias/brain, instead of waiting for the next 15-minute CronJob poll.
+package webhook
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+
+	batchv1 "k8s.io/api/batch/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/client-go/kubernetes"
+)
+
+// VerifySignature checks a Gitea webhook's X-Gitea-Signature header: a
+// hex-encoded HMAC-SHA256 of the raw request body, keyed by the shared
+// webhook secret. Constant-time compare — timing must not leak how much of
+// the signature matched.
+func VerifySignature(payload []byte, signatureHeader, secret string) bool {
+	if signatureHeader == "" {
+		return false
+	}
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write(payload)
+	expected := hex.EncodeToString(mac.Sum(nil))
+	return hmac.Equal([]byte(expected), []byte(signatureHeader))
+}
+
+// pushEvent is the subset of Gitea's push webhook payload this handler needs.
+type pushEvent struct {
+	Ref  string `json:"ref"`
+	Repo struct {
+		FullName string `json:"full_name"`
+	} `json:"repository"`
+}
+
+// TriggerJobFromCronJob reads the named CronJob's job template and creates a
+// new, uniquely-named Job from it — the same thing `kubectl create job
+// --from=cronjob/<name>` does. Reuses the CronJob's already-tested script
+// rather than re-implementing sync logic here.
+func TriggerJobFromCronJob(ctx context.Context, cs kubernetes.Interface, namespace, cronJobName string) (string, error) {
+	cj, err := cs.BatchV1().CronJobs(namespace).Get(ctx, cronJobName, metav1.GetOptions{})
+	if err != nil {
+		return "", fmt.Errorf("get cronjob %s/%s: %w", namespace, cronJobName, err)
+	}
+	job := &batchv1.Job{
+		ObjectMeta: metav1.ObjectMeta{
+			GenerateName: cronJobName + "-webhook-",
+			Namespace:    namespace,
+			Annotations: map[string]string{
+				"triggered-by": "brain-webhook",
+			},
+		},
+		Spec: cj.Spec.JobTemplate.Spec,
+	}
+	created, err := cs.BatchV1().Jobs(namespace).Create(ctx, job, metav1.CreateOptions{})
+	if err != nil {
+		return "", fmt.Errorf("create job from cronjob %s/%s: %w", namespace, cronJobName, err)
+	}
+	return created.Name, nil
+}
+
+// Handler is the HTTP handler for Gitea's push webhook on mathias/brain.
+type Handler struct {
+	Secret      string
+	Clientset   kubernetes.Interface
+	Namespace   string // e.g. "brain"
+	CronJobName string // e.g. "brain-sync"
+	WatchRepo   string // e.g. "mathias/brain"
+	Logger      *slog.Logger
+}
+
+func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		http.Error(w, "bad body", http.StatusBadRequest)
+		return
+	}
+	sig := r.Header.Get("X-Gitea-Signature")
+	if !VerifySignature(body, sig, h.Secret) {
+		http.Error(w, "bad signature", http.StatusUnauthorized)
+		return
+	}
+	var ev pushEvent
+	if err := json.Unmarshal(body, &ev); err != nil {
+		http.Error(w, "bad payload", http.StatusBadRequest)
+		return
+	}
+	if ev.Repo.FullName != h.WatchRepo || ev.Ref != "refs/heads/main" {
+		w.WriteHeader(http.StatusOK)
+		_, _ = fmt.Fprintf(w, "ignored: repo=%s ref=%s", ev.Repo.FullName, ev.Ref)
+		return
+	}
+	jobName, err := TriggerJobFromCronJob(r.Context(), h.Clientset, h.Namespace, h.CronJobName)
+	if err != nil {
+		h.Logger.Error("webhook: trigger job failed", "err", err)
+		http.Error(w, "trigger failed", http.StatusInternalServerError)
+		return
+	}
+	h.Logger.Info("webhook: triggered brain-sync job", "job", jobName)
+	w.WriteHeader(http.StatusOK)
+	_, _ = fmt.Fprintf(w, "triggered %s", jobName)
+}

ingestion/internal/webhook/webhook_test.go

@@ -0,0 +1,222 @@
+package webhook
+
+import (
+	"bytes"
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	batchv1 "k8s.io/api/batch/v1"
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/client-go/kubernetes/fake"
+	k8stesting "k8s.io/client-go/testing"
+)
+
+// newFakeClientset simulates the real API server's GenerateName expansion,
+// which the plain fake clientset tracker does not do on its own -- without
+// this, every created Job keeps an empty Name (a fake-clientset limitation,
+// not real API server behavior).
+func newFakeClientset(objects ...runtime.Object) *fake.Clientset {
+	cs := fake.NewSimpleClientset(objects...)
+	cs.PrependReactor("create", "jobs", func(action k8stesting.Action) (bool, runtime.Object, error) {
+		createAction := action.(k8stesting.CreateAction)
+		job, ok := createAction.GetObject().(*batchv1.Job)
+		if ok && job.Name == "" && job.GenerateName != "" {
+			job.Name = job.GenerateName + "test0001"
+		}
+		return false, nil, nil // not "handled" -- let the default reactor store it
+	})
+	return cs
+}
+
+func sign(t *testing.T, payload []byte, secret string) string {
+	t.Helper()
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write(payload)
+	return hex.EncodeToString(mac.Sum(nil))
+}
+
+func testLogger() *slog.Logger {
+	return slog.New(slog.NewTextHandler(os.Stderr, nil))
+}
+
+func fakeCronJob(namespace, name string) *batchv1.CronJob {
+	return &batchv1.CronJob{
+		ObjectMeta: metav1.ObjectMeta{Name: name, Namespace: namespace},
+		Spec: batchv1.CronJobSpec{
+			JobTemplate: batchv1.JobTemplateSpec{
+				Spec: batchv1.JobSpec{
+					Template: corev1.PodTemplateSpec{
+						Spec: corev1.PodSpec{
+							Containers: []corev1.Container{
+								{Name: "sync", Image: "alpine/git:v2.47.2"},
+							},
+							RestartPolicy: corev1.RestartPolicyNever,
+						},
+					},
+				},
+			},
+		},
+	}
+}
+
+// --------------------------------------------------------------------------- #
+// VerifySignature
+// --------------------------------------------------------------------------- #
+func TestVerifySignature_AcceptsCorrectHMAC(t *testing.T) {
+	payload := []byte(`{"ref":"refs/heads/main"}`)
+	secret := "s3cret"
+	sig := sign(t, payload, secret)
+	assert.True(t, VerifySignature(payload, sig, secret))
+}
+
+func TestVerifySignature_RejectsWrongSecret(t *testing.T) {
+	payload := []byte(`{"ref":"refs/heads/main"}`)
+	sig := sign(t, payload, "right-secret")
+	assert.False(t, VerifySignature(payload, sig, "wrong-secret"))
+}
+
+func TestVerifySignature_RejectsTamperedPayload(t *testing.T) {
+	secret := "s3cret"
+	sig := sign(t, []byte(`{"ref":"refs/heads/main"}`), secret)
+	assert.False(t, VerifySignature([]byte(`{"ref":"refs/heads/evil"}`), sig, secret))
+}
+
+func TestVerifySignature_RejectsEmptySignature(t *testing.T) {
+	assert.False(t, VerifySignature([]byte("payload"), "", "secret"))
+}
+
+// --------------------------------------------------------------------------- #
+// TriggerJobFromCronJob
+// --------------------------------------------------------------------------- #
+func TestTriggerJobFromCronJob_CreatesJobMatchingTemplate(t *testing.T) {
+	cs := newFakeClientset(fakeCronJob("brain", "brain-sync"))
+
+	jobName, err := TriggerJobFromCronJob(context.Background(), cs, "brain", "brain-sync")
+	require.NoError(t, err)
+	assert.NotEmpty(t, jobName)
+
+	jobs, err := cs.BatchV1().Jobs("brain").List(context.Background(), metav1.ListOptions{})
+	require.NoError(t, err)
+	require.Len(t, jobs.Items, 1)
+	assert.Equal(t, "alpine/git:v2.47.2", jobs.Items[0].Spec.Template.Spec.Containers[0].Image)
+}
+
+func TestTriggerJobFromCronJob_ErrorsWhenCronJobMissing(t *testing.T) {
+	cs := fake.NewSimpleClientset()
+	_, err := TriggerJobFromCronJob(context.Background(), cs, "brain", "brain-sync")
+	assert.Error(t, err)
+}
+
+// --------------------------------------------------------------------------- #
+// Handler.ServeHTTP
+// --------------------------------------------------------------------------- #
+func newTestHandler(cs *fake.Clientset) *Handler {
+	return &Handler{
+		Secret:      "s3cret",
+		Clientset:   cs,
+		Namespace:   "brain",
+		CronJobName: "brain-sync",
+		WatchRepo:   "mathias/brain",
+		Logger:      testLogger(),
+	}
+}
+
+func pushPayload(t *testing.T, repo, ref string) []byte {
+	t.Helper()
+	body := map[string]any{
+		"ref": ref,
+		"repository": map[string]any{
+			"full_name": repo,
+		},
+	}
+	b, err := json.Marshal(body)
+	require.NoError(t, err)
+	return b
+}
+
+func TestHandler_RejectsMissingSignature(t *testing.T) {
+	cs := fake.NewSimpleClientset(fakeCronJob("brain", "brain-sync"))
+	h := newTestHandler(cs)
+	payload := pushPayload(t, "mathias/brain", "refs/heads/main")
+	req := httptest.NewRequest(http.MethodPost, "/webhooks/brain-sync", bytes.NewReader(payload))
+	rec := httptest.NewRecorder()
+
+	h.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusUnauthorized, rec.Code)
+	jobs, _ := cs.BatchV1().Jobs("brain").List(context.Background(), metav1.ListOptions{})
+	assert.Empty(t, jobs.Items, "must not trigger a job on an unsigned request")
+}
+
+func TestHandler_RejectsWrongSignature(t *testing.T) {
+	cs := fake.NewSimpleClientset(fakeCronJob("brain", "brain-sync"))
+	h := newTestHandler(cs)
+	payload := pushPayload(t, "mathias/brain", "refs/heads/main")
+	req := httptest.NewRequest(http.MethodPost, "/webhooks/brain-sync", bytes.NewReader(payload))
+	req.Header.Set("X-Gitea-Signature", sign(t, payload, "not-the-real-secret"))
+	rec := httptest.NewRecorder()
+
+	h.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusUnauthorized, rec.Code)
+	jobs, _ := cs.BatchV1().Jobs("brain").List(context.Background(), metav1.ListOptions{})
+	assert.Empty(t, jobs.Items)
+}
+
+func TestHandler_IgnoresOtherRepos(t *testing.T) {
+	cs := fake.NewSimpleClientset(fakeCronJob("brain", "brain-sync"))
+	h := newTestHandler(cs)
+	payload := pushPayload(t, "mathias/some-other-repo", "refs/heads/main")
+	req := httptest.NewRequest(http.MethodPost, "/webhooks/brain-sync", bytes.NewReader(payload))
+	req.Header.Set("X-Gitea-Signature", sign(t, payload, "s3cret"))
+	rec := httptest.NewRecorder()
+
+	h.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	jobs, _ := cs.BatchV1().Jobs("brain").List(context.Background(), metav1.ListOptions{})
+	assert.Empty(t, jobs.Items, "must not trigger for a push to an unrelated repo")
+}
+
+func TestHandler_IgnoresNonMainBranch(t *testing.T) {
+	cs := fake.NewSimpleClientset(fakeCronJob("brain", "brain-sync"))
+	h := newTestHandler(cs)
+	payload := pushPayload(t, "mathias/brain", "refs/heads/some-feature-branch")
+	req := httptest.NewRequest(http.MethodPost, "/webhooks/brain-sync", bytes.NewReader(payload))
+	req.Header.Set("X-Gitea-Signature", sign(t, payload, "s3cret"))
+	rec := httptest.NewRecorder()
+
+	h.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	jobs, _ := cs.BatchV1().Jobs("brain").List(context.Background(), metav1.ListOptions{})
+	assert.Empty(t, jobs.Items, "must not trigger for a push to a non-main branch")
+}
+
+func TestHandler_TriggersJobOnValidMainPush(t *testing.T) {
+	cs := fake.NewSimpleClientset(fakeCronJob("brain", "brain-sync"))
+	h := newTestHandler(cs)
+	payload := pushPayload(t, "mathias/brain", "refs/heads/main")
+	req := httptest.NewRequest(http.MethodPost, "/webhooks/brain-sync", bytes.NewReader(payload))
+	req.Header.Set("X-Gitea-Signature", sign(t, payload, "s3cret"))
+	rec := httptest.NewRecorder()
+
+	h.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	jobs, err := cs.BatchV1().Jobs("brain").List(context.Background(), metav1.ListOptions{})
+	require.NoError(t, err)
+	assert.Len(t, jobs.Items, 1, "a valid push to main on the watched repo must trigger exactly one job")
+}