docs(topic-memory): align the guide with the shipped generic Artifact APIs

docs/en/docs/workflows/artifacts.md

@@ -5,8 +5,8 @@ description: Read current and historical revisions, then choose the write workfl
 
 # Manage Artifacts
 
-Artifacts preserve versioned results. Memory, Experience, Skill, Handoff, Profile, and Prompt have family-specific write rules;
-sharing a REST envelope does not make those workflows interchangeable.
+Artifacts preserve versioned results. Memory, Topic Memory, Experience, Skill, Handoff, Profile, and Prompt have
+family-specific write rules; sharing a REST envelope does not make those workflows interchangeable.
 
 ## Create and replace
 
@@ -44,11 +44,14 @@ The Python Client exposes this field as a string; use it directly instead of acc
 
 See the [complete HTTP API reference](/api/) for request fields, response models, and interactive operation examples.
 For authentication, concurrency control, and common call flows, see the [HTTP API guide](../develop/http-api.md).
-Topic Memory is currently a specialized read-only retrieval view and does not use the generic write operations above.
+Topic Memory also uses these generic interfaces: creation and replacement submit complete `title`, `summary`, and
+`detail` text without semantic generation. See [Use Topic Memory](topic-memory.md) for its dedicated search and scoped
+reads.
 
 ## Change content through its workflow
 
 - [Memory](memory-and-context.md): explicitly write, revise, or retire entries.
+- [Topic Memory](topic-memory.md): submit complete topic content directly, or read a topic by exact Revision.
 - [Experience and Skill](experience-and-skill-lifecycle.md): inspect and approve Candidates before publication or export.
 - [Handoff](handoff-with-codex.md): inspect and commit the current work boundary.
 - [Prompt](manage-prompts.md): customize operation guidance within one Scope.

docs/en/docs/workflows/topic-memory.md

@@ -5,9 +5,10 @@ description: Search topic summaries produced from long-running Sources and read
 
 # Use Topic Memory
 
-Topic Memory is a read-oriented Artifact family for long-running topics. It turns accumulated Sources in one Scope into a
-`title`, `summary`, and progressively disclosed `detail`, so an Agent can locate a topic first and read the full detail only
-when needed. It does not replace Memory, Experience, Skill, or Handoff.
+Topic Memory is an Artifact family for long-running topics. It turns accumulated Sources in one Scope into a `title`,
+`summary`, and progressively disclosed `detail`, so an Agent can locate a topic first and read the full detail only
+when needed; callers can also submit complete topic content directly through the generic interfaces in
+[Manage Artifacts](artifacts.md). It does not replace Memory, Experience, Skill, or Handoff.
 
 Topic Memory is Scope-local. Capturing a Source does not synchronously create a topic; configured background processing
 must advance it.
@@ -132,6 +133,31 @@ Content-Type: application/json
 The response contains `title`, `summary`, full `detail`, and `source_refs`. Even after the current topic head advances, the
 exact reference resolves to the same historical Revision for audit, citation, and progressive disclosure.
 
+## Write through the generic Artifact interfaces
+
+Besides Source processing, Topic Memory also uses the generic interfaces in [Manage Artifacts](artifacts.md):
+
+| Operation | Route |
+| --- | --- |
+| Create | `POST /v1/scopes/{scope_id}/artifacts` (`family` is `topic-memory`) |
+| Replace | `PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}` |
+| List heads | `GET /v1/scopes/{scope_id}/artifacts/{family}` |
+| Read a head, list revisions, read an exact revision | `GET /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}`, `.../revisions`, `.../revisions/{revision}` |
+| Read, replace, and query tags | `GET`/`PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}/tags`, `POST /v1/scopes/{scope_id}/artifact-tags/query` |
+
+Creation requires `scope.contribute` on the target Scope, and the request body carries the complete `title`, `summary`,
+and `detail`. The content skips semantic generation: topic content, the current head, chunks, and the retrieval indexes
+enabled by the deployment are committed in one operation, so generic reads and the dedicated search see the same topic
+version. A replace requires current `scope.admin` access, creates the next immutable Revision, and must carry the current
+head's `If-Match`.
+
+Manage tags as described in [Organize with tags](manage-artifact-tags.md); whole-Artifact Topic Memory tags are
+read with `scope.read` and modified with `scope.admin`.
+
+Publish one exact Revision into another Scope with `POST /v1/artifact-publications`, which requires `scope.admin` in
+both the source and target Scopes. Publication creates an independent identity in the target Scope and carries its
+retrieval indexes; tags and direct Sources are not copied.
+
 ## Assemble into PreparedContext
 
 To inject topic summaries into one Agent turn, add `topic-memory` explicitly to `assembly` in
@@ -164,8 +190,7 @@ HTTP-only and is not exposed as an MCP tool.
 
 ## Current boundaries
 
-- There is no generic Topic Memory create, update, delete, or retire endpoint; topics are generated from Sources and stored as immutable Revisions.
-- Topic Memory is not in the current Taggable Artifact family list, so Memory, Experience, Skill, and Handoff tag APIs do not apply.
+- The generic interfaces do not accept Topic Memory delete or retire operations; topics are stored as immutable Revisions, and background processing or an explicit write advances the current head.
 - Source capture does not synchronously generate a topic; background processing and the required generation capability are needed.
 - Backups, recovery, worker availability, and retrieval failures belong to [deployment and operations](../operate/index.md), not this lifecycle.
 

docs/zh/docs/workflows/artifacts.md

@@ -5,7 +5,7 @@ description: 读取当前与历史版本，并按 Artifact 家族选择修改方
 
 # 管理 Artifact
 
-Artifact 保存有版本的结果。Memory、Experience、Skill、Handoff、Profile 和 Prompt 各自有不同的写入规则；
+Artifact 保存有版本的结果。Memory、Topic Memory、Experience、Skill、Handoff、Profile 和 Prompt 各自有不同的写入规则；
 共用 REST 外层结构不意味着可以互换这些工作流。
 
 ## 创建和替换
@@ -42,11 +42,13 @@ Python Client 将该字段表示为字符串，请直接使用，不再访问枚
 
 完整的请求字段、响应模型和可调试的接口示例请参阅[完整 HTTP API 参考](/api/)。
 接口鉴权、并发控制和常用调用流程见 [HTTP API 使用说明](../develop/http-api.md)。
-Topic Memory 当前是专用的只读检索视图，不使用上述通用写接口。
+Topic Memory 也使用上述通用接口：创建和整体替换提交完整的 `title`、`summary` 和 `detail`，内容不经过语义生成。
+它的专用搜索和范围化读取见[使用 Topic Memory](topic-memory.md)。
 
 ## 按对应工作流修改
 
 - [Memory](memory-and-context.md)：显式写入、修订或退役条目。
+- [Topic Memory](topic-memory.md)：直接提交完整主题内容，或按精确 Revision 读取主题。
 - [Experience 与 Skill](experience-and-skill-lifecycle.md)：发布或导出前检查并批准 Candidate。
 - [Handoff](handoff-with-codex.md)：检查并提交当前工作边界。
 - [Prompt](manage-prompts.md)：在一个 Scope 内自定义操作提示词。

docs/zh/docs/workflows/topic-memory.md

@@ -5,9 +5,9 @@ description: 从长期 Source 处理中查找主题摘要，并按精确 Revisio
 
 # 使用 Topic Memory
 
-Topic Memory 是面向长期主题的只读检索型 Artifact family。它把一个 Scope 中持续累积的 Source 处理成
-`title`、`summary` 和渐进式展开的 `detail`，适合先定位主题、再按需读取全文；它不替代 Memory、Experience、Skill
-或 Handoff。
+Topic Memory 是面向长期主题的 Artifact family。它把一个 Scope 中持续累积的 Source 处理成 `title`、`summary`
+和渐进式展开的 `detail`，适合先定位主题、再按需读取全文；调用方也可以按[管理 Artifact](artifacts.md)中的通用接口
+直接提交完整主题内容。它不替代 Memory、Experience、Skill 或 Handoff。
 
 Topic Memory 只属于当前 Scope。Source 被采集后不会同步生成主题，必须由已配置的后台处理能力推进。
 
@@ -122,6 +122,29 @@ Content-Type: application/json
 响应包含 `title`、`summary`、完整 `detail` 和 `source_refs`。即使主题的当前 head 后续前进，精确引用仍指向同一
 历史 Revision，适合审计、引用和渐进式 disclosure。
 
+## 通过通用 Artifact 接口写入
+
+除 Source 处理外，Topic Memory 也使用[管理 Artifact](artifacts.md)中的通用接口：
+
+| 操作 | 路由 |
+| --- | --- |
+| 创建 | `POST /v1/scopes/{scope_id}/artifacts`（`family` 为 `topic-memory`） |
+| 整体替换 | `PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}` |
+| 列举 head | `GET /v1/scopes/{scope_id}/artifacts/{family}` |
+| 读取 head、列举修订、读取精确修订 | `GET /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}`、`.../revisions`、`.../revisions/{revision}` |
+| 标签读写与查询 | `GET`/`PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}/tags`、`POST /v1/scopes/{scope_id}/artifact-tags/query` |
+
+创建需要目标 Scope 的 `scope.contribute` 权限，请求体提交完整的 `title`、`summary` 和 `detail`。内容不经过语义
+生成，主题内容、当前 head、分块和当前部署启用的检索索引会在同一次提交内完成，因此通用读取和专用检索看到的是同一个
+主题版本。整体替换需要当前 Scope 的 `scope.admin` 权限，生成下一条不可变 Revision，并且必须携带当前 head 的
+`If-Match`。
+
+标签按[使用标签整理内容](manage-artifact-tags.md)管理；Topic Memory 的整体标签使用 `scope.read` 读取、
+`scope.admin` 修改。
+
+把某个精确 Revision 发布到另一个 Scope 使用 `POST /v1/artifact-publications`，需要源 Scope 和目标 Scope 的
+`scope.admin` 权限。发布会在目标 Scope 中创建独立身份并携带其检索索引；标签和直接 Source 不会复制。
+
 ## 组装到 PreparedContext
 
 需要把主题摘要注入一次 Agent turn 时，在 `POST /v1/context/prepare` 的 `assembly` 中显式加入
@@ -151,8 +174,7 @@ MCP 暴露只读的 `search_topic_memory` 和 `get_topic_memory` 工具。Agent
 
 ## 当前边界
 
-- 没有通用的 Topic Memory create、update、delete 或 retire 接口；主题由 Source 处理产生，并以不可变 Revision 保存。
-- Topic Memory 不在当前 Taggable Artifact family 列表中，不能套用 Memory、Experience、Skill 或 Handoff 的标签接口。
+- 通用接口不接受 Topic Memory delete 或 retire 操作；主题以不可变 Revision 保存，当前 head 由后台处理或显式写入推进。
 - Source capture 不会同步生成主题；需要后台处理和相应的生成能力。
 - 备份、恢复、worker 可用性和检索故障属于[部署与运维](../operate/index.md)，不是本生命周期的一部分。