feat(backthink/admin): ③b — rag/delete 真实现 + D1 推送出口钩子(自建优先→个推兜底) + api-reference 补 D2/D3/D5 补丁

- B5: POST /admin/rag/delete 真做(DeleteDocument→DeleteProject 级联删章节+索引清理, owner+审计, 200/404/500, 500降级兜底); users/iot scenarios+rules 诚实501(无用户表/IoT场景规则模型, 消息写明缺什么, 不伪造), 锁住 501+not_implemented
- D1: backthink/push_outlet.go PushExporter{Export}; pushOutlet 自建HTTP(2xx=送达, token仅Authorization头+error脱敏)优先→Getui兜底(未接入, 诚实日志'getui not integrated'+(false,nil)); backthink.Deps.Exporter → pusher.withExporter, Push 在WS/IM后 exportAsync(detached+5s超时, 失败仅日志, 不破坏现有投递, 限流不上报); config PushOutletConfig(PUSH_EXPORTER_* + GETUI_*占位)
- 前端 Rag.tsx/api.ts 删除后 reload + 类型; Docs/api-client v0.31 + api-reference(#23 owner/200-404, §8.4, 端点表PATCH/DELETE messages + pinned + messages?q=)
- 测试(push_outlet/admin_rag_delete/admin_honest501/knowledge store), 后端+前端build全绿+3平台交叉编译
- 刻意: Getui SDK 未接入(无SDK不硬造), 主人自建服务填 PUSH_EXPORTER_URL/TOKEN 即可

internal/config/config.go

@@ -30,6 +30,7 @@ type Config struct {
 	IoT         IoTConfig
 	Voice       VoiceConfig
 	Background  BackgroundConfig
+	PushOutlet  PushOutletConfig
 	WSHub       WSHubConfig
 	ExecSandbox ExecSandbox
 	MCP         MCPConfig
@@ -177,6 +178,31 @@ type BackgroundConfig struct {
 	KindWindowSec         int  `env:"THINK_KIND_WINDOW_SEC" default:"7200"`
 }
 
+// PushOutletConfig configures the proactive push outlet (D1, design/12 §4/§6).
+// Proactive messages are mirrored to the owner's self-hosted unified push
+// service (primary); Getui (个推) is the deferred fallback for when that service
+// is unavailable. The Getui* fields are reserved placeholders — the SDK is not
+// integrated, so an unavailable primary logs the pending fallback rather than
+// pretending to push.
+type PushOutletConfig struct {
+	// Enabled turns the outlet hook on. When false no export is attempted.
+	Enabled bool `env:"PUSH_EXPORTER_ENABLED" default:"false"`
+	// URL is the self-hosted unified push service endpoint (HTTP POST JSON).
+	// Empty leaves the primary tier unconfigured.
+	URL string `env:"PUSH_EXPORTER_URL"`
+	// Token is sent as "Authorization: Bearer <token>"; it is never logged.
+	Token string `env:"PUSH_EXPORTER_TOKEN"`
+	// TimeoutSec bounds one export attempt. Zero uses the service default (5s).
+	TimeoutSec int `env:"PUSH_EXPORTER_TIMEOUT_SEC" default:"5"`
+
+	// Getui* are reserved for the fallback tier; the SDK is not integrated yet,
+	// so these values are read but unused (kept so the env contract is stable).
+	GetuiAppID        string `env:"GETUI_APP_ID"`
+	GetuiAppKey       string `env:"GETUI_APP_KEY"`
+	GetuiMasterSecret string `env:"GETUI_MASTER_SECRET"`
+	GetuiBaseURL      string `env:"GETUI_BASE_URL"`
+}
+
 // WSHubConfig holds the WebSocket hub limits.
 type WSHubConfig struct {
 	MaxConnections     int `env:"WS_MAX_CONNECTIONS" default:"1000"`

internal/config/config_test.go

@@ -66,6 +66,35 @@ func TestLoad_EnvOverridesDefault(t *testing.T) {
 	}
 }
 
+func TestLoad_PushOutletEnv(t *testing.T) {
+	t.Setenv("JWT_SECRET", strings.Repeat("s", 40))
+	t.Setenv("PUSH_EXPORTER_ENABLED", "true")
+	t.Setenv("PUSH_EXPORTER_URL", "https://push.example.com/hook")
+	t.Setenv("PUSH_EXPORTER_TOKEN", "tok")
+	t.Setenv("PUSH_EXPORTER_TIMEOUT_SEC", "9")
+	t.Setenv("GETUI_APP_ID", "app-id")
+
+	cfg, err := Load("")
+	if err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+	if !cfg.PushOutlet.Enabled {
+		t.Error("PushOutlet.Enabled = false, want true")
+	}
+	if cfg.PushOutlet.URL != "https://push.example.com/hook" {
+		t.Errorf("PushOutlet.URL = %q, want the configured endpoint", cfg.PushOutlet.URL)
+	}
+	if cfg.PushOutlet.Token != "tok" {
+		t.Errorf("PushOutlet.Token = %q, want tok", cfg.PushOutlet.Token)
+	}
+	if cfg.PushOutlet.TimeoutSec != 9 {
+		t.Errorf("PushOutlet.TimeoutSec = %d, want 9", cfg.PushOutlet.TimeoutSec)
+	}
+	if cfg.PushOutlet.GetuiAppID != "app-id" {
+		t.Errorf("PushOutlet.GetuiAppID = %q, want app-id", cfg.PushOutlet.GetuiAppID)
+	}
+}
+
 func TestLoad_DotEnvThenProcessEnv(t *testing.T) {
 	path := writeEnvFile(t, `PORT=7000
 LOG_LEVEL=error

internal/runtime/knowledge/store.go

@@ -15,9 +15,9 @@
 // stores it as a project plus its chapters, making it text/keyword-searchable
 // immediately. Semantic/vector embedding of an imported document is a graceful
 // no-op here (this data source holds no vector index); the existing semantic path
-// still ranks project-linked memories via the retriever. Deletion remains
-// unimplemented (M10) and returns ErrWriteUnsupported so the admin handler
-// answers honestly instead of fabricating a success.
+// still ranks project-linked memories via the retriever. DeleteDocument removes a
+// document (its project entry and, in one transaction, every chapter that
+// references it) so the import/delete pair is a real round-trip.
 package knowledge
 
 import (
@@ -36,10 +36,15 @@ import (
 	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/memory/projectindex"
 )
 
-// ErrWriteUnsupported is returned by DeleteDocument. Deletion is milestone M10;
-// the admin handler maps it to a clear 501 so the frontend can explain rather
-// than show a placeholder alert.
-var ErrWriteUnsupported = errors.New("knowledge: delete is not implemented in this milestone")
+// ErrWriteUnsupported is returned by a knowledge store implementation that does
+// not support document deletion. *Store implements DeleteDocument, so it never
+// returns this; it remains for alternate/degraded implementations the admin
+// handler maps to a clear 501 rather than a fabricated success.
+var ErrWriteUnsupported = errors.New("knowledge: delete is not supported by this store")
+
+// ErrDocumentNotFound is returned by DeleteDocument when the id is blank or no
+// knowledge document (project-index entry) carries it.
+var ErrDocumentNotFound = errors.New("knowledge: document not found")
 
 // defaultTopK bounds the semantic retrieval path.
 const defaultTopK = 8
@@ -322,10 +327,27 @@ func (s *Store) IndexDocument(ctx context.Context, doc Doc) error {
 	return nil
 }
 
-// DeleteDocument is not implemented in this milestone. It returns
-// ErrWriteUnsupported so the handler answers honestly (delete = M10).
-func (s *Store) DeleteDocument(_ context.Context, _ string) error {
-	return ErrWriteUnsupported
+// DeleteDocument removes a knowledge document: the project-index entry and, in
+// the same transaction, every chapter that references it (projectindex.DeleteProject
+// cascades the chunk cleanup). It returns ErrDocumentNotFound for a blank id or
+// one with no project entry, and an error when no project index is wired (there
+// is nowhere to delete from, so a fabricated success is never returned).
+func (s *Store) DeleteDocument(ctx context.Context, id string) error {
+	docID := strings.TrimSpace(id)
+	if docID == "" {
+		return fmt.Errorf("knowledge: delete document: %w", ErrDocumentNotFound)
+	}
+	if s.projects == nil {
+		return errors.New("knowledge: delete document: project index store is not configured")
+	}
+	if err := s.projects.DeleteProject(ctx, docID); err != nil {
+		if errors.Is(err, projectindex.ErrProjectNotFound) {
+			return fmt.Errorf("knowledge: delete document %q: %w", docID, ErrDocumentNotFound)
+		}
+		return fmt.Errorf("knowledge: delete document %q: %w", docID, err)
+	}
+	s.log.Info("deleted document", "project", docID)
+	return nil
 }
 
 // maxChapterRunes bounds a single chapter's content length. Paragraphs longer

internal/runtime/knowledge/store_test.go

@@ -99,10 +99,56 @@ func TestIndexDocumentRequiresProjectStore(t *testing.T) {
 	}
 }
 
-func TestDeleteDocumentStillUnsupported(t *testing.T) {
+// TestDeleteDocumentRemovesProjectAndChapters proves delete is a real round-trip:
+// the document disappears from the list and the search, and deleting it again is
+// a not-found rather than a silent success.
+func TestDeleteDocumentRemovesProjectAndChapters(t *testing.T) {
 	t.Parallel()
-	s := New(Deps{Log: testLogger()})
-	if err := s.DeleteDocument(context.Background(), "any"); !errors.Is(err, ErrWriteUnsupported) {
-		t.Fatalf("DeleteDocument err = %v, want ErrWriteUnsupported", err)
+	ctx := context.Background()
+	s := newTestStore(t)
+	if err := s.IndexDocument(ctx, Doc{
+		ID:      "doc-1",
+		Name:    "Cyrene 设计",
+		Content: "第一段：项目描述。\n\n第二段：内部实现要点。",
+	}); err != nil {
+		t.Fatalf("IndexDocument: %v", err)
+	}
+
+	if err := s.DeleteDocument(ctx, "doc-1"); err != nil {
+		t.Fatalf("DeleteDocument: %v", err)
+	}
+	docs, err := s.ListDocuments(ctx)
+	if err != nil {
+		t.Fatalf("ListDocuments: %v", err)
+	}
+	if len(docs) != 0 {
+		t.Fatalf("documents = %+v, want empty after delete", docs)
+	}
+	hits, err := s.Search(ctx, "内部实现")
+	if err != nil {
+		t.Fatalf("Search: %v", err)
+	}
+	if len(hits) != 0 {
+		t.Fatalf("hits = %+v, want none after delete", hits)
+	}
+
+	if err := s.DeleteDocument(ctx, "doc-1"); !errors.Is(err, ErrDocumentNotFound) {
+		t.Fatalf("second DeleteDocument err = %v, want ErrDocumentNotFound", err)
+	}
+}
+
+func TestDeleteDocumentBlankIDNotFound(t *testing.T) {
+	t.Parallel()
+	s := newTestStore(t)
+	if err := s.DeleteDocument(context.Background(), "  "); !errors.Is(err, ErrDocumentNotFound) {
+		t.Fatalf("DeleteDocument blank id err = %v, want ErrDocumentNotFound", err)
+	}
+}
+
+func TestDeleteDocumentRequiresProjectStore(t *testing.T) {
+	t.Parallel()
+	s := New(Deps{Log: testLogger()}) // projects == nil
+	if err := s.DeleteDocument(context.Background(), "doc-1"); err == nil {
+		t.Fatal("DeleteDocument without a project index should error")
 	}
 }

internal/services/backthink/backthink.go

@@ -82,6 +82,10 @@ type Deps struct {
 	Active ActiveClient
 	// IM is the IM bridge sink, used as the fallback when no active client is up.
 	IM IMAdapter
+	// Exporter mirrors a proactive message to the external push outlet (the
+	// owner's self-hosted unified push service, then Getui). Optional: nil
+	// disables the hook. It never blocks or breaks the Active/IM delivery.
+	Exporter PushExporter
 	// Gate is the proactive-push rate limiter. Nil builds a default from Config.
 	Gate PushGate
 	// DB is the SQLite handle for the think store. Required.
@@ -146,7 +150,7 @@ func New(cfg Config, deps Deps) (*Backthink, error) {
 	}
 	pusher := deps.Pusher
 	if pusher == nil {
-		pusher = newPusher(deps.Active, deps.IM, gate, log)
+		pusher = newPusher(deps.Active, deps.IM, gate, log).withExporter(deps.Exporter)
 	}
 
 	now := deps.Now

internal/services/backthink/push.go

@@ -128,20 +128,34 @@ type Pusher interface {
 
 // pusher is the concrete Pusher: it consults the gate, then routes the message to
 // exactly one target — the active client for a "web" hint, otherwise the IM bridge.
+// After the local delivery it mirrors the message to the optional push outlet
+// (self-hosted service → Getui fallback) without blocking that delivery.
 type pusher struct {
-	active ActiveClient
-	im     IMAdapter
-	gate   PushGate
-	log    *slog.Logger
+	active   ActiveClient
+	im       IMAdapter
+	gate     PushGate
+	exporter PushExporter
+	log      *slog.Logger
+	// exportDone, when non-nil, receives one value after each asynchronous export
+	// completes. It exists so tests can deterministically observe the hook; the
+	// send is non-blocking, so a full channel never stalls the exporter.
+	exportDone chan struct{}
 }
 
 // newPusher builds a Pusher from the optional active-client sink, IM sink and
 // rate gate. Any of them may be nil; a nil target simply makes that route
-// unavailable.
+// unavailable. The push outlet is attached separately with withExporter.
 func newPusher(active ActiveClient, im IMAdapter, gate PushGate, log *slog.Logger) *pusher {
 	return &pusher{active: active, im: im, gate: gate, log: log}
 }
 
+// withExporter attaches the push outlet hook and returns the pusher for fluent
+// use. A nil exporter leaves the hook disabled.
+func (p *pusher) withExporter(exporter PushExporter) *pusher {
+	p.exporter = exporter
+	return p
+}
+
 // Push implements Pusher: it applies the rate gate, then routes the message to a
 // single target. A "web" hint reaches the active web/native client; every other
 // hint ("im", "auto", or a concrete platform) goes over the IM bridge once, where
@@ -192,6 +206,11 @@ func (p *pusher) Push(ctx context.Context, req PushRequest) PushResult {
 	if res.Pushed && p.gate != nil && !eventDriven {
 		p.gate.RecordPush(kind)
 	}
+	// D1: mirror the proactive message to the external push outlet (self-hosted
+	// unified push service → Getui fallback). Fire-and-forget: a slow or failing
+	// outlet never delays or breaks the local delivery above, and a rate-limited
+	// push returned before reaching here.
+	p.exportAsync(msg)
 	res = annotateHint(res, req.ChannelHint)
 	if eventDriven {
 		res.Bypassed = true
@@ -200,6 +219,33 @@ func (p *pusher) Push(ctx context.Context, req PushRequest) PushResult {
 	return res
 }
 
+// exportAsync reports msg to the push outlet on a detached, bounded goroutine so
+// the proactive path never blocks on the outlet. A nil exporter (hook disabled)
+// or a nil outlet result is a no-op; a delivery miss or error is only logged.
+func (p *pusher) exportAsync(msg adapter.UnifiedMessage) {
+	if p.exporter == nil {
+		return
+	}
+	timeout := defaultExportTimeout
+	go func() {
+		ctx, cancel := context.WithTimeout(context.Background(), timeout)
+		defer cancel()
+		delivered, err := p.exporter.Export(ctx, msg)
+		switch {
+		case err != nil:
+			p.log.Warn("push outlet export failed", "error", err)
+		case !delivered:
+			p.log.Info("push outlet did not deliver", "hint", "getui fallback not integrated")
+		}
+		if p.exportDone != nil {
+			select {
+			case p.exportDone <- struct{}{}:
+			default:
+			}
+		}
+	}()
+}
+
 // pushActive delivers only to the active web/native client.
 func (p *pusher) pushActive(ctx context.Context, msg adapter.UnifiedMessage) PushResult {
 	if p.active != nil {

internal/services/backthink/push_outlet.go

@@ -0,0 +1,193 @@
+package backthink
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"strings"
+	"time"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/channel/adapter"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
+)
+
+// The push outlet (D1, design/12 §4/§6): proactive messages are mirrored to an
+// external push service so the owner's mobile client is reached even when no
+// WebSocket client or IM channel is live. Delivery is two-tier by design:
+//
+//  1. the owner's self-hosted unified push service (primary; PUSH_EXPORTER_URL),
+//  2. Getui (个推) as the fallback for when the self-hosted service is down.
+//
+// Tier 2 has no SDK integration yet, so an unavailable primary logs an explicit
+// "Getui fallback not integrated" note and reports not-delivered instead of
+// pretending the message went out. The hook is fire-and-forget: it never delays
+// or breaks the existing active-client / IM delivery.
+
+// defaultExportTimeout bounds one export attempt so a hung endpoint cannot pin a
+// goroutine forever.
+const defaultExportTimeout = 5 * time.Second
+
+// maxExportResponseBytes caps how much of the outlet's response body is drained
+// before the connection is reused, so a hostile/buggy endpoint cannot stream an
+// unbounded body into memory.
+const maxExportResponseBytes = 4 << 10
+
+// PushExporter reports one proactive message to an external push outlet. Export
+// must be safe for concurrent use and must honor ctx. A nil error with
+// delivered=false means the outlet could not deliver (for example the fallback
+// tier is not wired); the caller treats that as a logged miss, never a failure
+// of the local push path.
+type PushExporter interface {
+	Export(ctx context.Context, msg adapter.UnifiedMessage) (delivered bool, err error)
+}
+
+// PushOutletConfig carries the push-outlet wiring. Enabled=false disables the
+// hook entirely (NewPushOutlet returns nil). URL/Token/Timeout describe the
+// self-hosted primary service; the Getui* fields are reserved for the deferred
+// fallback and are not consumed yet.
+type PushOutletConfig struct {
+	// Enabled turns the outlet hook on.
+	Enabled bool
+	// URL is the self-hosted unified push service endpoint (HTTP POST JSON).
+	// Empty leaves the primary tier unconfigured.
+	URL string
+	// Token is sent as "Authorization: Bearer <token>". It is never logged.
+	Token string
+	// Timeout bounds one export attempt. Zero uses defaultExportTimeout.
+	Timeout time.Duration
+	// Log is the base logger. Nil uses a discard logger.
+	Log *slog.Logger
+}
+
+// NewPushOutlet builds the two-tier push outlet from cfg. It returns nil when
+// the hook is disabled, so the pusher simply skips the export step. When it is
+// enabled the primary tier is the self-hosted HTTP endpoint (present only when
+// URL is set) and the fallback tier is Getui, which is not integrated yet.
+func NewPushOutlet(cfg PushOutletConfig) PushExporter {
+	if !cfg.Enabled {
+		return nil
+	}
+	log := logger.WithSource(baseLog(cfg.Log), "services/backthink/push_outlet")
+	timeout := cfg.Timeout
+	if timeout <= 0 {
+		timeout = defaultExportTimeout
+	}
+	var primary PushExporter
+	if url := strings.TrimSpace(cfg.URL); url != "" {
+		primary = &httpPushExporter{
+			url:    url,
+			token:  cfg.Token,
+			client: &http.Client{Timeout: timeout},
+		}
+	} else {
+		log.Warn("push outlet enabled but PUSH_EXPORTER_URL is empty; only the (unwired) Getui fallback remains")
+	}
+	log.Info("push outlet configured", "primary", primary != nil, "fallback", "getui (not integrated)")
+	return &pushOutlet{primary: primary, log: log}
+}
+
+// pushOutlet is the two-tier exporter: self-hosted service first, Getui second.
+// The fallback is nil until the Getui SDK is integrated, so a primary miss is
+// logged and reported as not delivered rather than silently dropped.
+type pushOutlet struct {
+	primary  PushExporter
+	fallback PushExporter
+	log      *slog.Logger
+}
+
+// Export implements PushExporter. It tries the primary tier and, when that does
+// not deliver, the fallback tier. With no fallback wired it logs the pending
+// integration and returns (false, nil): the caller treats that as a miss, never
+// as a reason to fail the proactive push.
+func (o *pushOutlet) Export(ctx context.Context, msg adapter.UnifiedMessage) (bool, error) {
+	if o.primary != nil {
+		delivered, err := o.primary.Export(ctx, msg)
+		if err == nil && delivered {
+			return true, nil
+		}
+		if err != nil {
+			o.log.Warn("push outlet primary failed", "error", err)
+		} else {
+			o.log.Warn("push outlet primary did not deliver")
+		}
+	}
+	if o.fallback != nil {
+		return o.fallback.Export(ctx, msg)
+	}
+	o.log.Info("push outlet not delivered; getui fallback not integrated",
+		"hint", "wire the Getui SDK + GETUI_* credentials to enable the fallback tier")
+	return false, nil
+}
+
+// pushExportPayload is the JSON body POSTed to the self-hosted push service. It
+// is deliberately small and stable: the service owns device targeting, the
+// message carries only what is needed to render and de-duplicate it.
+type pushExportPayload struct {
+	// Source identifies the producer so the service can route/filter.
+	Source string `json:"source"`
+	// Title is a short display title (the persona name).
+	Title string `json:"title"`
+	// Content is the proactive message body (already stripped of internal
+	// decision markers by buildProactiveMessage).
+	Content string `json:"content"`
+	// Platform is the outbound platform tag (cyrene-backthink or a concrete IM
+	// platform).
+	Platform string `json:"platform"`
+	// Timestamp is the message time in Unix milliseconds.
+	Timestamp int64 `json:"timestamp"`
+}
+
+// httpPushExporter posts the message to the self-hosted push service. A 2xx
+// response means delivered; any other status or transport error is an error.
+// The token travels only in the Authorization header and never reaches a log.
+type httpPushExporter struct {
+	url    string
+	token  string
+	client *http.Client
+}
+
+// Export implements PushExporter over HTTP POST JSON.
+func (e *httpPushExporter) Export(ctx context.Context, msg adapter.UnifiedMessage) (bool, error) {
+	body, err := json.Marshal(pushExportPayload{
+		Source:    "cyrene/backthink",
+		Title:     msg.Sender.DisplayName,
+		Content:   msg.Content,
+		Platform:  msg.Platform,
+		Timestamp: msg.Timestamp.UnixMilli(),
+	})
+	if err != nil {
+		return false, fmt.Errorf("push outlet: marshal payload: %w", err)
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, e.url, bytes.NewReader(body))
+	if err != nil {
+		return false, fmt.Errorf("push outlet: build request: %w", e.redact(err))
+	}
+	req.Header.Set("Content-Type", "application/json")
+	if e.token != "" {
+		req.Header.Set("Authorization", "Bearer "+e.token)
+	}
+	resp, err := e.client.Do(req)
+	if err != nil {
+		return false, fmt.Errorf("push outlet: post: %w", e.redact(err))
+	}
+	defer func() { _ = resp.Body.Close() }()
+	_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, maxExportResponseBytes))
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return false, fmt.Errorf("push outlet: unexpected status %d", resp.StatusCode)
+	}
+	return true, nil
+}
+
+// redact removes the endpoint URL from a transport error so a secret embedded in
+// the URL (for example a query token) never reaches a log line.
+func (e *httpPushExporter) redact(err error) error {
+	if err == nil || e.url == "" {
+		return err
+	}
+	msg := strings.ReplaceAll(err.Error(), e.url, "[push-outlet-url]")
+	return fmt.Errorf("%s", msg)
+}

internal/services/backthink/push_outlet_test.go

@@ -0,0 +1,261 @@
+package backthink
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/channel/adapter"
+)
+
+// mockExporter records exported messages and can block or fail on demand so the
+// pusher hook's non-blocking / failure-tolerant behaviour is testable.
+type mockExporter struct {
+	mu        sync.Mutex
+	msgs      []adapter.UnifiedMessage
+	delivered bool
+	err       error
+	started   chan struct{}
+	startOnce sync.Once
+	release   chan struct{}
+}
+
+func (m *mockExporter) Export(ctx context.Context, msg adapter.UnifiedMessage) (bool, error) {
+	m.startOnce.Do(func() {
+		if m.started != nil {
+			close(m.started)
+		}
+	})
+	if m.release != nil {
+		<-m.release
+	}
+	m.mu.Lock()
+	m.msgs = append(m.msgs, msg)
+	m.mu.Unlock()
+	return m.delivered, m.err
+}
+
+func (m *mockExporter) messages() []adapter.UnifiedMessage {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return append([]adapter.UnifiedMessage(nil), m.msgs...)
+}
+
+// TestPushOutletHTTPPrimaryDelivers proves the self-hosted service is the
+// primary tier: the payload is POSTed with the bearer token and a 2xx response
+// is reported as delivered.
+func TestPushOutletHTTPPrimaryDelivers(t *testing.T) {
+	t.Parallel()
+	type payload struct {
+		Source    string `json:"source"`
+		Title     string `json:"title"`
+		Content   string `json:"content"`
+		Platform  string `json:"platform"`
+		Timestamp int64  `json:"timestamp"`
+	}
+	var (
+		got  payload
+		auth string
+		ct   string
+	)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		auth = r.Header.Get("Authorization")
+		ct = r.Header.Get("Content-Type")
+		if err := json.NewDecoder(r.Body).Decode(&got); err != nil {
+			t.Errorf("decode payload: %v", err)
+		}
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer srv.Close()
+
+	exp := NewPushOutlet(PushOutletConfig{
+		Enabled: true,
+		URL:     srv.URL,
+		Token:   "s3cret-token",
+		Timeout: 2 * time.Second,
+		Log:     discardLog(),
+	})
+	if exp == nil {
+		t.Fatal("NewPushOutlet returned nil for an enabled outlet")
+	}
+	delivered, err := exp.Export(context.Background(), adapter.UnifiedMessage{
+		Platform:  "cyrene-backthink",
+		Content:   "晚安，早点睡。",
+		Sender:    adapter.Actor{DisplayName: "Cyrene"},
+		Timestamp: time.UnixMilli(1700000000000),
+	})
+	if err != nil || !delivered {
+		t.Fatalf("Export = (%v, %v), want (true, nil)", delivered, err)
+	}
+	if got.Source != "cyrene/backthink" || got.Title != "Cyrene" || got.Content != "晚安，早点睡。" || got.Platform != "cyrene-backthink" {
+		t.Fatalf("payload = %+v, want source/title/content/platform set", got)
+	}
+	if got.Timestamp != 1700000000000 {
+		t.Fatalf("timestamp = %d, want 1700000000000", got.Timestamp)
+	}
+	if auth != "Bearer s3cret-token" {
+		t.Fatalf("Authorization = %q, want the bearer token", auth)
+	}
+	if ct != "application/json" {
+		t.Fatalf("Content-Type = %q, want application/json", ct)
+	}
+}
+
+// TestPushOutletUnreachableLogsGetuiFallback asserts an unreachable primary is a
+// logged miss (not an error), names the pending Getui fallback, and never logs
+// the token.
+func TestPushOutletUnreachableLogsGetuiFallback(t *testing.T) {
+	t.Parallel()
+	srv := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
+	url := srv.URL
+	srv.Close() // now unreachable
+
+	var buf bytes.Buffer
+	log := slog.New(slog.NewTextHandler(&buf, nil))
+	exp := NewPushOutlet(PushOutletConfig{Enabled: true, URL: url, Token: "s3cret-token", Timeout: 300 * time.Millisecond, Log: log})
+
+	delivered, err := exp.Export(context.Background(), adapter.UnifiedMessage{Content: "hi"})
+	if err != nil {
+		t.Fatalf("Export err = %v, want nil (logged miss)", err)
+	}
+	if delivered {
+		t.Fatal("Export delivered = true, want false for an unreachable primary")
+	}
+	if !strings.Contains(buf.String(), "getui") {
+		t.Fatalf("log = %q, want the pending Getui fallback note", buf.String())
+	}
+	if strings.Contains(buf.String(), "s3cret-token") {
+		t.Fatalf("log leaked the token: %q", buf.String())
+	}
+}
+
+// TestPushOutletHTTPErrorReportsMiss asserts a non-2xx primary response is a miss.
+func TestPushOutletHTTPErrorReportsMiss(t *testing.T) {
+	t.Parallel()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, "nope", http.StatusInternalServerError)
+	}))
+	defer srv.Close()
+
+	exp := NewPushOutlet(PushOutletConfig{Enabled: true, URL: srv.URL, Timeout: 2 * time.Second, Log: discardLog()})
+	delivered, err := exp.Export(context.Background(), adapter.UnifiedMessage{Content: "hi"})
+	if err != nil {
+		t.Fatalf("Export err = %v, want nil (logged miss)", err)
+	}
+	if delivered {
+		t.Fatal("Export delivered = true, want false for a 500 response")
+	}
+}
+
+// TestNewPushOutletDisabledOrUnconfigured covers the two degraded shapes: the
+// hook off (nil) and enabled without a primary URL (miss + Getui note).
+func TestNewPushOutletDisabledOrUnconfigured(t *testing.T) {
+	t.Parallel()
+	if exp := NewPushOutlet(PushOutletConfig{Enabled: false, URL: "http://example.invalid"}); exp != nil {
+		t.Fatalf("NewPushOutlet disabled = %v, want nil", exp)
+	}
+
+	var buf bytes.Buffer
+	log := slog.New(slog.NewTextHandler(&buf, nil))
+	exp := NewPushOutlet(PushOutletConfig{Enabled: true, Log: log})
+	if exp == nil {
+		t.Fatal("NewPushOutlet enabled without a URL = nil, want a fallback-only outlet")
+	}
+	delivered, err := exp.Export(context.Background(), adapter.UnifiedMessage{Content: "hi"})
+	if err != nil || delivered {
+		t.Fatalf("Export = (%v, %v), want (false, nil)", delivered, err)
+	}
+	if !strings.Contains(buf.String(), "getui") {
+		t.Fatalf("log = %q, want the Getui fallback note", buf.String())
+	}
+}
+
+// TestPusherExportsProactiveToOutlet asserts the hook mirrors the delivered
+// proactive message to the outlet after the IM delivery.
+func TestPusherExportsProactiveToOutlet(t *testing.T) {
+	t.Parallel()
+	exp := &mockExporter{delivered: true}
+	im := &mockIMAdapter{}
+	p := newPusher(nil, im, &mockGate{allow: true}, discardLog()).withExporter(exp)
+	p.exportDone = make(chan struct{}, 1)
+
+	res := p.Push(context.Background(), PushRequest{Message: adapter.UnifiedMessage{Content: "在吗"}})
+	if !res.Pushed || res.Route != RouteIMBridge {
+		t.Fatalf("push = %+v, want pushed via IM bridge", res)
+	}
+	if im.count() != 1 {
+		t.Fatalf("im calls = %d, want 1", im.count())
+	}
+	select {
+	case <-p.exportDone:
+	case <-time.After(2 * time.Second):
+		t.Fatal("export hook did not run")
+	}
+	msgs := exp.messages()
+	if len(msgs) != 1 || msgs[0].Content != "在吗" {
+		t.Fatalf("exported = %+v, want the proactive content", msgs)
+	}
+}
+
+// TestPusherExportHookNonBlockingAndFailureTolerant asserts a hung/failing outlet
+// never delays the push and never turns a delivered proactive message into a
+// failure.
+func TestPusherExportHookNonBlockingAndFailureTolerant(t *testing.T) {
+	t.Parallel()
+	started := make(chan struct{})
+	release := make(chan struct{})
+	exp := &mockExporter{delivered: false, err: errors.New("outlet down"), started: started, release: release}
+	im := &mockIMAdapter{}
+	p := newPusher(nil, im, &mockGate{allow: true}, discardLog()).withExporter(exp)
+	p.exportDone = make(chan struct{}, 1)
+
+	begin := time.Now()
+	res := p.Push(context.Background(), PushRequest{Message: adapter.UnifiedMessage{Content: "hi"}})
+	if elapsed := time.Since(begin); elapsed > 100*time.Millisecond {
+		t.Fatalf("Push blocked on the outlet for %v, want non-blocking", elapsed)
+	}
+	if !res.Pushed || res.Route != RouteIMBridge {
+		t.Fatalf("push = %+v, want pushed via IM bridge despite the outlet failure", res)
+	}
+	select {
+	case <-started:
+	case <-time.After(2 * time.Second):
+		t.Fatal("exporter was never invoked")
+	}
+	close(release)
+	select {
+	case <-p.exportDone:
+	case <-time.After(2 * time.Second):
+		t.Fatal("export hook did not finish")
+	}
+}
+
+// TestPusherRateLimitedPushIsNotExported asserts a rate-limited push never
+// reaches the outlet: the hook mirrors real proactive sends only.
+func TestPusherRateLimitedPushIsNotExported(t *testing.T) {
+	t.Parallel()
+	exp := &mockExporter{delivered: true}
+	p := newPusher(nil, &mockIMAdapter{}, &mockGate{allow: false}, discardLog()).withExporter(exp)
+	p.exportDone = make(chan struct{}, 1)
+
+	res := p.Push(context.Background(), PushRequest{Message: adapter.UnifiedMessage{Content: "hi"}})
+	if res.Route != RouteRateLimited {
+		t.Fatalf("route = %q, want rate_limited", res.Route)
+	}
+	select {
+	case <-p.exportDone:
+		t.Fatal("rate-limited push should not be exported")
+	case <-time.After(50 * time.Millisecond):
+	}
+	if len(exp.messages()) != 0 {
+		t.Fatalf("exported = %+v, want none", exp.messages())
+	}
+}

internal/services/backthink/sinks.go

@@ -25,10 +25,10 @@ func (b *Backthink) SetIMSink(im IMAdapter) {
 	b.rebuildPusherLocked()
 }
 
-// rebuildPusherLocked replaces the pusher from the current sinks and gate. The
-// caller must hold b.mu.
+// rebuildPusherLocked replaces the pusher from the current sinks, gate and push
+// outlet. The caller must hold b.mu.
 func (b *Backthink) rebuildPusherLocked() {
-	b.pusher = newPusher(b.deps.Active, b.deps.IM, b.gate, b.log)
+	b.pusher = newPusher(b.deps.Active, b.deps.IM, b.gate, b.log).withExporter(b.deps.Exporter)
 }
 
 // currentPusher returns the active pusher under the lifecycle lock, so a sink

internal/services/gateway/admin.go

@@ -496,11 +496,6 @@ type ragQueryRequest struct {
 	Query string `json:"query"`
 }
 
-// ragDeleteRequest is the POST /api/v1/admin/rag/delete body.
-type ragDeleteRequest struct {
-	ID string `json:"id"`
-}
-
 // adminListRag lists the knowledge-base documents and, when ?query= is present,
 // returns the matching hits too. Without a wired RagStore it degrades to an empty
 // list (backward compatible — never a 500).
@@ -555,33 +550,6 @@ func (s *Server) adminSearchRag(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"query": req.Query, "hits": ragHitsFrom(hits)})
 }
 
-// adminDeleteRag answers the document delete honestly: write operations
-// (upload/chunk/embed/delete) are milestone M10, so it returns a clear 501 rather
-// than a fabricated success. The route is audited as an admin write.
-func (s *Server) adminDeleteRag(w http.ResponseWriter, r *http.Request) {
-	if s.rag == nil {
-		s.auditClaims(r, "rag.delete", "error")
-		writeError(w, &apperr.AppError{Code: "not_implemented", Message: "知识库 RAG 服务未配置（未注入 RagStore）", HTTPCode: http.StatusNotImplemented})
-		return
-	}
-	var req ragDeleteRequest
-	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "invalid request body"))
-		return
-	}
-	if strings.TrimSpace(req.ID) == "" {
-		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "id is required"))
-		return
-	}
-	if err := s.rag.DeleteDocument(r.Context(), req.ID); err != nil {
-		s.auditClaims(r, "rag.delete", "error")
-		writeError(w, &apperr.AppError{Code: "not_implemented", Message: "知识库写操作（上传/分块/嵌入/删除）由 M10 后端提供", HTTPCode: http.StatusNotImplemented})
-		return
-	}
-	s.auditClaims(r, "rag.delete", "ok")
-	writeJSON(w, http.StatusOK, map[string]any{"id": req.ID})
-}
-
 // ragDocsFrom maps knowledge docs to their admin wire shape.
 func ragDocsFrom(docs []knowledge.Doc) []AdminRagDoc {
 	out := make([]AdminRagDoc, 0, len(docs))

internal/services/gateway/admin_honest501_test.go

@@ -0,0 +1,36 @@
+package gateway
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/auth"
+)
+
+// TestAdminMissingStoreWritesHonest501 locks the B5 red line for the endpoints
+// whose backing store does not exist yet: they must answer 501 not_implemented
+// with an explanatory message, never a fabricated success. User creation has no
+// user table/login to persist into, and IoT has no scenario/rule model or store.
+func TestAdminMissingStoreWritesHonest501(t *testing.T) {
+	t.Parallel()
+	srv, ts, jwt := buildEnv(t, cfgDefault(), Deps{})
+	_ = srv
+	tok := signAny(t, jwt, "acct", auth.RoleOwner)
+
+	cases := []string{
+		"/api/v1/admin/users",
+		"/api/v1/admin/iot/scenarios",
+		"/api/v1/admin/iot/rules",
+	}
+	for _, path := range cases {
+		resp, body := doReq(t, http.MethodPost, ts.URL+path, map[string]any{"name": "x"}, tok)
+		if resp.StatusCode != http.StatusNotImplemented {
+			t.Fatalf("%s status = %d, want 501 (body=%s)", path, resp.StatusCode, body)
+		}
+		wantErrorShape(t, body)
+		if !strings.Contains(string(body), "not_implemented") {
+			t.Fatalf("%s body = %s, want not_implemented code", path, body)
+		}
+	}
+}

internal/services/gateway/admin_rag_delete_test.go

@@ -0,0 +1,96 @@
+package gateway
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/auth"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/knowledge"
+)
+
+// TestAdminRagDeleteRemovesDocument proves the delete write path is real: the
+// indexed document (project entry + its chapters) is gone from the list and the
+// search, and deleting it again answers 404 rather than a fabricated success.
+func TestAdminRagDeleteRemovesDocument(t *testing.T) {
+	t.Parallel()
+	ctx := context.Background()
+	rag := newRagStoreForGateway(t)
+	if err := rag.IndexDocument(ctx, knowledge.Doc{
+		ID:      "doc-1",
+		Name:    "Cyrene 设计",
+		Desc:    "v2 设计文档",
+		Content: "第一段：项目描述。\n\n第二段：内部实现要点。",
+	}); err != nil {
+		t.Fatalf("IndexDocument: %v", err)
+	}
+
+	srv, ts, jwt := buildEnv(t, cfgDefault(), Deps{RAG: rag})
+	_ = srv
+	tok := signAny(t, jwt, "acct", auth.RoleOwner)
+
+	resp, body := doReq(t, http.MethodPost, ts.URL+"/api/v1/admin/rag/delete", map[string]any{"id": "doc-1"}, tok)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("delete status = %d, want 200 (body=%s)", resp.StatusCode, body)
+	}
+	var res struct {
+		ID      string `json:"id"`
+		Deleted bool   `json:"deleted"`
+	}
+	if err := json.Unmarshal(decodeBody(t, body)["data"], &res); err != nil {
+		t.Fatalf("decode: %v (body=%s)", err, body)
+	}
+	if res.ID != "doc-1" || !res.Deleted {
+		t.Fatalf("response = %+v, want id=doc-1 deleted=true", res)
+	}
+
+	docs, err := rag.ListDocuments(ctx)
+	if err != nil {
+		t.Fatalf("ListDocuments: %v", err)
+	}
+	if len(docs) != 0 {
+		t.Fatalf("documents = %+v, want empty after delete", docs)
+	}
+	hits, err := rag.Search(ctx, "内部实现")
+	if err != nil {
+		t.Fatalf("Search: %v", err)
+	}
+	if len(hits) != 0 {
+		t.Fatalf("hits = %+v, want none after delete", hits)
+	}
+
+	resp2, body2 := doReq(t, http.MethodPost, ts.URL+"/api/v1/admin/rag/delete", map[string]any{"id": "doc-1"}, tok)
+	if resp2.StatusCode != http.StatusNotFound {
+		t.Fatalf("second delete status = %d, want 404 (body=%s)", resp2.StatusCode, body2)
+	}
+	wantErrorShape(t, body2)
+}
+
+// TestAdminRagDeleteUnwired501 asserts an unconfigured RAG service still answers
+// honestly instead of pretending the document was removed.
+func TestAdminRagDeleteUnwired501(t *testing.T) {
+	t.Parallel()
+	srv, ts, jwt := buildEnv(t, cfgDefault(), Deps{})
+	_ = srv
+	tok := signAny(t, jwt, "acct", auth.RoleOwner)
+
+	resp, body := doReq(t, http.MethodPost, ts.URL+"/api/v1/admin/rag/delete", map[string]any{"id": "doc-1"}, tok)
+	if resp.StatusCode != http.StatusNotImplemented {
+		t.Fatalf("status = %d, want 501 (body=%s)", resp.StatusCode, body)
+	}
+	wantErrorShape(t, body)
+}
+
+// TestAdminRagDeleteRequiresOwner asserts the write route stays owner-gated.
+func TestAdminRagDeleteRequiresOwner(t *testing.T) {
+	t.Parallel()
+	srv, ts, jwt := buildEnv(t, cfgDefault(), Deps{RAG: newRagStoreForGateway(t)})
+	_ = srv
+	tok := signAny(t, jwt, "acct", auth.RoleAdmin)
+
+	resp, _ := doReq(t, http.MethodPost, ts.URL+"/api/v1/admin/rag/delete", map[string]any{"id": "doc-1"}, tok)
+	if resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("status = %d, want 403", resp.StatusCode)
+	}
+}

internal/services/gateway/admin_write_iot_automations.go

@@ -56,17 +56,29 @@ func (s *Server) adminIoTControl(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, iotDeviceSummary{ID: dev.ID, Name: dev.Name, Type: dev.Type, State: dev.State, Online: dev.Online})
 }
 
-// adminIoTScenario answers honestly: the IoT subsystem has no scenario store yet
-// (it owns device list/control/status only), so scenario write lands in M10.
+// adminIoTScenario answers honestly: the IoT subsystem owns device
+// list/control/status only (the Provider interface has no scenario model or
+// store), so there is nothing to persist a scenario into. It reports the missing
+// store rather than fabricating one.
 func (s *Server) adminIoTScenario(w http.ResponseWriter, r *http.Request) {
 	s.auditClaims(r, "iot.scenario", "error")
-	writeError(w, &apperr.AppError{Code: "not_implemented", Message: "IoT 场景存储为 M10 提供（当前 IoT 仅有设备列表/控制/状态）", HTTPCode: http.StatusNotImplemented})
+	writeError(w, &apperr.AppError{
+		Code:     "not_implemented",
+		Message:  "IoT 场景未实现：IoT 子系统仅有设备列表/控制/状态（Provider 接口无场景模型与存储）；场景 CRUD 需先新增模型 + 执行器",
+		HTTPCode: http.StatusNotImplemented,
+	})
 }
 
-// adminIoTRule answers honestly: no IoT automation-rule store exists yet.
+// adminIoTRule answers honestly: no IoT automation-rule model or store exists
+// (the generic automations service runs cron/event rules, not device-state
+// conditions with device actions), so a rule cannot be persisted or executed.
 func (s *Server) adminIoTRule(w http.ResponseWriter, r *http.Request) {
 	s.auditClaims(r, "iot.rule", "error")
-	writeError(w, &apperr.AppError{Code: "not_implemented", Message: "IoT 自动化规则存储为 M10 提供（当前 IoT 仅有设备列表/控制/状态）", HTTPCode: http.StatusNotImplemented})
+	writeError(w, &apperr.AppError{
+		Code:     "not_implemented",
+		Message:  "IoT 自动化规则未实现：IoT 子系统无规则模型与存储（通用 automations 服务只跑 cron/事件规则，不含设备状态条件 + 设备动作执行器）",
+		HTTPCode: http.StatusNotImplemented,
+	})
 }
 
 // mapIotError maps iot sentinel errors to HTTP errors.

internal/services/gateway/admin_write_memory_rag.go

@@ -2,6 +2,7 @@ package gateway
 
 import (
 	"encoding/json"
+	"errors"
 	"net/http"
 	"strings"
 
@@ -125,3 +126,45 @@ func (s *Server) adminIndexRag(w http.ResponseWriter, r *http.Request) {
 	s.auditClaims(r, "rag.index", "ok")
 	writeJSON(w, http.StatusCreated, map[string]any{"name": name})
 }
+
+// ragDeleteRequest is the POST /api/v1/admin/rag/delete body.
+type ragDeleteRequest struct {
+	ID string `json:"id"`
+}
+
+// adminDeleteRag removes a knowledge document by id: the store deletes the
+// project-index entry and cascades its chapters. A missing document is answered
+// with 404, a store that cannot delete with a clear 501, and any other failure
+// with 500 — never a fabricated success. The route is owner-gated and audited.
+func (s *Server) adminDeleteRag(w http.ResponseWriter, r *http.Request) {
+	if s.rag == nil {
+		s.auditClaims(r, "rag.delete", "error")
+		writeError(w, &apperr.AppError{Code: "not_implemented", Message: "知识库 RAG 服务未配置（未注入 RagStore）", HTTPCode: http.StatusNotImplemented})
+		return
+	}
+	var req ragDeleteRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "invalid request body"))
+		return
+	}
+	id := strings.TrimSpace(req.ID)
+	if id == "" {
+		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "id is required"))
+		return
+	}
+	if err := s.rag.DeleteDocument(r.Context(), id); err != nil {
+		s.auditClaims(r, "rag.delete", "error")
+		switch {
+		case errors.Is(err, knowledge.ErrDocumentNotFound):
+			writeError(w, apperr.Wrap(apperr.ErrNotFound, "not_found", "知识库文档 %q 不存在", id))
+		case errors.Is(err, knowledge.ErrWriteUnsupported):
+			writeError(w, &apperr.AppError{Code: "not_implemented", Message: "该知识库存储不支持删除", HTTPCode: http.StatusNotImplemented})
+		default:
+			s.log.Error("rag delete", "id", id, "err", err)
+			writeError(w, apperr.Wrap(apperr.ErrInternal, "rag_delete_failed", "failed to delete knowledge document"))
+		}
+		return
+	}
+	s.auditClaims(r, "rag.delete", "ok")
+	writeJSON(w, http.StatusOK, map[string]any{"id": id, "deleted": true})
+}

internal/services/gateway/admin_write_personas_users.go

@@ -132,12 +132,18 @@ func (s *Server) adminUpdatePersona(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, personaSummaryOf(p, characterFromRequest(req)))
 }
 
-// adminCreateUser answers honestly: there is no persistent user table yet (the
-// deployment is a single admin account + API keys), so user creation is deferred
-// to M10 rather than fabricated.
+// adminCreateUser answers honestly: there is no persistent user table and no
+// user-authenticated login to back one (the deployment is a single admin
+// account from .env plus runtime API keys; design/11 is single-user first), so
+// user creation would be a row nobody could log in with. It reports the missing
+// store instead of fabricating a user.
 func (s *Server) adminCreateUser(w http.ResponseWriter, r *http.Request) {
 	s.auditClaims(r, "user.create", "error")
-	writeError(w, &apperr.AppError{Code: "not_implemented", Message: "新增用户/角色存储为 M10 提供（当前为单 admin + APIKey 现状）", HTTPCode: http.StatusNotImplemented})
+	writeError(w, &apperr.AppError{
+		Code:     "not_implemented",
+		Message:  "新增用户/角色未实现：无用户表，登录仅用 .env 单 admin（ADMIN_USERNAME/PASSWORD），角色为 owner>admin>viewer 常量；多用户存储与登录接入需先设计（design/11 单用户为主）",
+		HTTPCode: http.StatusNotImplemented,
+	})
 }
 
 // apiKeyIssueRequest is the POST /api/v1/admin/users/apikey body.

internal/services/gateway/extra_test.go

@@ -1526,7 +1526,9 @@ func TestAdminRagEmptyWhenUnwired(t *testing.T) {
 	}
 }
 
-func TestAdminRagDeleteNotImplemented(t *testing.T) {
+// TestAdminRagDeleteUnsupportedStore501 asserts a store that cannot delete is
+// answered with an honest 501 rather than a fabricated success.
+func TestAdminRagDeleteUnsupportedStore501(t *testing.T) {
 	t.Parallel()
 	srv, ts, jwt := buildEnv(t, cfgDefault(), Deps{RAG: &stubRag{err: knowledge.ErrWriteUnsupported}})
 	_ = srv
@@ -1537,8 +1539,8 @@ func TestAdminRagDeleteNotImplemented(t *testing.T) {
 		t.Fatalf("status = %d, want 501 (body=%s)", resp.StatusCode, body)
 	}
 	wantErrorShape(t, body)
-	if !strings.Contains(string(body), "M10") {
-		t.Fatalf("error body = %s, want M10 write message", body)
+	if !strings.Contains(string(body), "not_implemented") {
+		t.Fatalf("error body = %s, want not_implemented code", body)
 	}
 }
 

internal/services/gateway/server.go

@@ -235,9 +235,11 @@ type OwnerRegistrar interface {
 }
 
 // RagStore backs the admin knowledge-base RAG module (design/10 §3.12 module 8).
-// *runtime/knowledge.Store is the production implementation. Every method is
-// read-only for this milestone: IndexDocument/DeleteDocument return a clear
-// "write lands in M10" error rather than a fabricated success.
+// *runtime/knowledge.Store is the production implementation: it lists/searches
+// the project index, imports a document (chunk + index) and deletes one
+// (project entry + cascaded chapters). An implementation that cannot write
+// reports a clear error (knowledge.ErrWriteUnsupported) rather than a fabricated
+// success; the handlers map a missing document to 404.
 type RagStore interface {
 	// ListDocuments enumerates the knowledge-base documents (project-index
 	// entries).
@@ -245,9 +247,10 @@ type RagStore interface {
 	// Search answers a knowledge-base query (line-level hierarchy + optional
 	// semantic/vector ranking).
 	Search(ctx context.Context, query string) ([]knowledge.Hit, error)
-	// IndexDocument uploads/chunks/embeds a document. M10; returns an error.
+	// IndexDocument uploads/chunks/embeds a document into the project index.
 	IndexDocument(ctx context.Context, doc knowledge.Doc) error
-	// DeleteDocument removes a document. M10; returns an error.
+	// DeleteDocument removes a document (and its chapters) by id, returning
+	// knowledge.ErrDocumentNotFound when no such document exists.
 	DeleteDocument(ctx context.Context, id string) error
 }
 
@@ -509,7 +512,6 @@ func (s *Server) Handler() http.Handler {
 	mux.Handle("GET /api/v1/admin/backthink", adminAuth(http.HandlerFunc(s.adminListBackthink)))
 	mux.Handle("GET /api/v1/admin/rag", adminAuth(http.HandlerFunc(s.adminListRag)))
 	mux.Handle("POST /api/v1/admin/rag/query", adminAuth(http.HandlerFunc(s.adminSearchRag)))
-	mux.Handle("POST /api/v1/admin/rag/delete", adminAuth(http.HandlerFunc(s.adminDeleteRag)))
 	mux.Handle("GET /api/v1/admin/observability/metrics", adminAuth(http.HandlerFunc(s.adminObservabilityMetrics)))
 	mux.Handle("GET /api/v1/admin/observability/trace", adminAuth(http.HandlerFunc(s.adminObservabilityTrace)))
 	mux.Handle("GET /api/v1/admin/observability/audit", adminAuth(http.HandlerFunc(s.adminObservabilityAudit)))
@@ -549,6 +551,7 @@ func (s *Server) Handler() http.Handler {
 	mux.Handle("POST /api/v1/admin/memories", ownerAuth(http.HandlerFunc(s.adminAddMemory)))
 	mux.Handle("POST /api/v1/admin/memories/search", ownerAuth(http.HandlerFunc(s.adminMemorySearch)))
 	mux.Handle("POST /api/v1/admin/rag", ownerAuth(http.HandlerFunc(s.adminIndexRag)))
+	mux.Handle("POST /api/v1/admin/rag/delete", ownerAuth(http.HandlerFunc(s.adminDeleteRag)))
 	mux.Handle("GET /api/v1/admin/sessions/{id}/export", adminAuth(http.HandlerFunc(s.adminExportSession)))
 	mux.Handle("POST /api/v1/admin/system/revoke-keys", ownerAuth(http.HandlerFunc(s.adminRevokeAllKeys)))
 	mux.Handle("POST /api/v1/admin/system/rotate-jwt", ownerAuth(http.HandlerFunc(s.adminRotateJWT)))