docs(release): prepare v0.5.0 notes

docs/architecture/discord-general-advisor.md

@@ -1,6 +1,6 @@
 # Discord general advisor
 
-This contract defines a fake-first, response-only advisor for Discord users who need routing and operational architecture guidance before choosing a managed Project Manager channel, OpenClaw capability path, or approval-gated workflow.
+This contract defines a fake-first, response-only usage coach for Discord users who need routing, command-family help, prompt feedback, information placement, and operational architecture guidance before choosing a managed Project Manager channel, OpenClaw capability path, or approval-gated workflow.
 
 This is a contract only. It does not prove live Discord routing, live OpenClaw execution, prompt execution, durable writes, GitHub mutations, production credentials, publishing, scheduling, or Buffer activity.
 
@@ -10,8 +10,10 @@ This is a contract only. It does not prove live Discord routing, live OpenClaw e
 2. Classify the request topic and risk without hydrating durable private state.
 3. Recommend a target scope, category, channel, or handoff path using existing routing contracts.
 4. Explain why the route fits and whether approval is required.
-5. Optionally return copyable handoff text for the recommended channel.
-6. Ask a clarifying question instead of guessing when scope, project, network, or action risk is ambiguous.
+5. For help requests, explain command families and safe prompt patterns using fake/sanitized examples.
+6. For prompt review requests, suggest a safer prompt before execution and keep `write_executed: false`.
+7. Optionally return copyable handoff text for the recommended channel.
+8. Ask a clarifying question instead of guessing when scope, project, network, privacy, or action risk is ambiguous.
 
 ## Contract dependencies
 
@@ -31,11 +33,12 @@ The advisor depends on:
 | --- | --- |
 | `origin_kind` | Source surface such as `discord-general-channel` or `discord-managed-channel`. |
 | `runtime_namespace` | `discord-project-manager/runtime/discord/<guild-id>/<channel-id>`. |
-| `question_type` | `where_should_this_go`, `architecture_help`, `handoff_copy`, or `clarify_route`. |
-| `requested_topic` | Topic family such as `project`, `category`, `channel`, `context`, `skill`, `profile`, `capability`, `strategy`, `task`, `analytics`, or `publishing`. |
+| `question_type` | `where_should_this_go`, `architecture_help`, `command_help`, `prompt_feedback`, `handoff_copy`, or `clarify_route`. |
+| `requested_topic` | Topic family such as `project`, `category`, `channel`, `context`, `skill`, `profile`, `capability`, `strategy`, `task`, `analytics`, `publishing`, or `process_release`. |
 | `known_scope` | `global`, `project`, `network`, or `unknown`. |
 | `known_project_ref` | Sanitized project ref or `unknown`. |
 | `write_like` | Whether the request appears to create, update, store, publish, schedule, commit, or deploy. |
+| `user_message_language` | Review language tag for the current Discord message. Fake fixtures currently use `en`, `es`, or `und` for unknown/ambiguous language. |
 
 ## Advisor response schema
 
@@ -48,7 +51,57 @@ The advisor depends on:
 | `approval_required` | Whether exact `approve write` is required before persistence or external effects. |
 | `write_executed` | Always `false` in this slice. |
 | `handoff_message` | Optional copyable message for the recommended channel. |
+| `command_families` | For `command_help`, a compact list of response-only command/workflow families with fake examples. |
+| `prompt_pattern` | A recommended prompt shape such as goal, scope, constraints, privacy, and desired output. |
+| `safer_prompt` | For `prompt_feedback`, a rewritten prompt that narrows scope and avoids private data or live action. |
 | `clarifying_question` | Required when route or risk is ambiguous. |
+| `prose_reply_language` | Language tag used for natural-language, user-facing prose; must match `user_message_language`. |
+| `technical_tokens_language` | Always `en` for routes, paths, schema keys, commands, and exact approval phrases. |
+| `language_policy` | Canonical marker `prose-matches-current-message; technical-tokens-stay-english`. |
+
+## Command family guide
+
+The advisor can explain available command families without executing them. Use sanitized examples only:
+
+| Family | Use when | Fake prompt pattern |
+| --- | --- | --- |
+| `context` | Capture project assumptions or constraints for discussion. | "Where should I put this sanitized project constraint?" |
+| `profile` | Discuss private writing preferences or identity/style bindings. | "Should this preference live in `profile` or project context?" |
+| `skill` | Propose workflow skill behavior or scoped enablement. | "Review whether this belongs in a scoped skill before I ask for approval." |
+| `capability` | Evaluate runtime connector/tool availability. | "What approval is needed before enabling a fake connector?" |
+| `strategy` | Explore positioning, roadmap, or tradeoffs. | "Route this roadmap tradeoff for project-demo-egdev." |
+| `task` | Prepare actionable implementation work. | "Turn this approved strategy into task-channel handoff copy." |
+| `analytics` | Discuss metrics/trends before ingestion is approved. | "Where should a sanitized trend summary go?" |
+| `publishing` | Check publishing/scheduling readiness. | "Review publishing readiness; do not publish or schedule." |
+| `process/release` | Discuss release, review, incident, or operational process. | "Where should this release checklist question go?" |
+
+## Prompt review guide
+
+For proposed prompts, the advisor should review before execution: identify privacy risk, unclear routing, write-like effects, missing approval, and output ambiguity. It should then return `safer_prompt` that includes goal, target route, sanitized inputs, non-goals, approval state, and requested output. The advisor still keeps `write_executed: false` and does not run the revised prompt.
+
+## Information placement guide
+
+Use this placement map before recommending a workflow:
+
+| Information type | Placement |
+| --- | --- |
+| Durable project assumptions | `context` |
+| Private style or identity preferences | `profile` |
+| Workflow behavior or enablement | `skill` |
+| Runtime tool or connector availability | `capability` |
+| Roadmap, positioning, tradeoffs | `strategy` |
+| Approved implementation steps | `task` |
+| Metrics, trends, source summaries | `analytics` |
+| Publishing/scheduling readiness | `publishing` |
+| Review, release, incident, governance | `process/release` |
+
+## Workflow handoff template
+
+Copyable handoff messages should use this safe shape:
+
+```text
+In <recommended_route>: <sanitized goal>. Context: <fake or sanitized project ref>. Constraints: response-only advice first; no durable writes, live actions, publishing, scheduling, or GitHub mutations without approval.
+```
 
 ## Topic routing guide
 
@@ -66,6 +119,13 @@ The advisor depends on:
 | Runtime capability or connector configuration | Global/project `config` or skills governance, approval-gated before enablement. |
 | Analytics or trend ingestion | Strategy/advisory route until v0.5 capability is approved. |
 | Publishing or scheduling | `publishing-connector-readiness`; no publish/schedule before explicit approval. |
+| Review, release, incident, or governance process | Project `decisions` channel or the explicit release/process workflow; no release, commit, PR, or publication action before approval. |
+
+## Response-language rule
+
+The advisor's user-facing prose replies must match the user's current Discord message language when the language is known. This is a per-message fake-first contract; the fixture metadata proves only the intended policy, not live language detection. Routes such as `project:egdev:strategy`, paths, schema keys, commands, skill names, and exact approval phrases such as `approve write` remain English inside otherwise localized prose.
+
+When the language is unknown or genuinely ambiguous, use `user_message_language: und`, `prose_reply_language: und`, and ask a short language-neutral clarification instead of defaulting silently to English.
 
 ## Safety rules
 
@@ -89,8 +149,9 @@ This contract does not:
 
 ## Validation checklist
 
-- [ ] Fixture covers project, category, channel, private preference, capability, social bootstrap, publishing, and ambiguity scenarios.
+- [ ] Fixture covers project, category, channel, private preference, capability, social bootstrap, publishing, command help, prompt feedback, workflow handoff, process/release, and ambiguity scenarios.
 - [ ] Every response includes a route or clarifying question, reason, approval state, and `write_executed: false`.
+- [ ] Every scenario includes `user_message_language`, matching `prose_reply_language`, `language_policy: prose-matches-current-message; technical-tokens-stay-english`, and `technical_tokens_language: en`.
 - [ ] Write-like advice stays approval-gated.
 - [ ] Copyable handoff text is safe and does not include private IDs or transcripts.
 - [ ] No live/prod/mutation claims or real Discord identifiers are introduced.

docs/architecture/discord-runtime-orchestrator.md

@@ -59,6 +59,7 @@ The orchestrator depends on:
 | `resolved_route` | Approved `project_slug` and `network_slug`, or `none`. |
 | `normalized_channel_name` | Reviewable fake channel-name evidence. |
 | `user_role` | Minimal fake operator role or capability hint. |
+| `user_message_language` | Review language tag for the current Discord message. Fake fixtures currently use `en`, `es`, or `und` for unknown/ambiguous language. |
 
 ## Artifact classification
 
@@ -118,6 +119,19 @@ The active OpenClaw skill surface is curated, not “everything in `skills/` mea
 | Scoped workflow | `brand-context`, `content-ledger`, `strategy-planner`, `linkedin-weekly-planner`, `x-queue-planner`, `on-demand-brief-planner` | Invoked only when selected by global/category/channel scoped resolution. |
 | Preserved protocol | Gentle-AI SDD assets under `.openclaw/skills` | Used only through the `gentle-sdd` backend boundary for `sdd_dev_work`; product workflow skills are not selected as the executor for OpenClaw skill-development handoffs. |
 
+## Response-language policy
+
+For Discord-originated turns, user-facing prose replies must match the user's current Discord message language. The language decision is per-message and fake-first in this contract; no live detection is proven. Commands, code snippets, schema keys, routes, paths, skill names, backend names, and exact approval phrases remain English even when the surrounding prose is not English.
+
+Reviewable language metadata:
+
+| Field | Required? | Purpose |
+| --- | --- | --- |
+| `user_message_language` | Yes | Language tag inferred for the current Discord message in the fake event envelope. |
+| `prose_reply_language` | Yes | Language tag used for natural-language, user-facing prose. Must match `user_message_language`; use `und` only for an explicit language-neutral clarification fallback. |
+| `language_policy` | Yes | Canonical marker `prose-matches-current-message; technical-tokens-stay-english`. |
+| `technical_tokens_language` | Yes | Always `en` for commands, snippets, schema keys, routes, paths, approval phrases, and contract identifiers. |
+
 ## Permission and confirmation gates
 
 The orchestrator must separate runner selection from persistence permission.
@@ -144,7 +158,8 @@ Each orchestrated turn should leave reviewable metadata for the contract:
 - selected runner/backend;
 - permission gate state;
 - prompt execution state (`none` in this slice);
-- writeback policy classification.
+- writeback policy classification;
+- user message language, prose reply language, technical token language, and the language-policy marker.
 
 ## Historical anchors
 
@@ -176,4 +191,5 @@ This contract does not:
 - [ ] `sdd_dev_work` routes to `backend: gentle-sdd` only.
 - [ ] Clarification fallback stays `response-only` and `reject` for writeback.
 - [ ] Prompt execution remains `none` in every scenario.
+- [ ] Every scenario includes `user_message_language`, matching `prose_reply_language`, `language_policy: prose-matches-current-message; technical-tokens-stay-english`, and `technical_tokens_language: en`.
 - [ ] No raw Discord IDs, credential env names, live/prod claims, or GitHub mutation claims are introduced.

docs/operations/content-ideation-source-ingestion-flow.md

@@ -0,0 +1,74 @@
+<!-- markdownlint-disable MD013 -->
+
+# Content ideation source ingestion flow
+
+Issue #200 defines a fake-first contract for turning RSS/feed URLs and webpage sources into bounded, provenance-tagged ideation signals before any durable planning or ledger write.
+
+## Quick path
+
+1. Register only repo-safe demo sources in git; keep private source URLs in private runtime configuration.
+2. Read sources through approved read-only adapters: RSS adapter choice is pending spike, webpage extraction should prefer `web-readability`, and search/fetch providers may be evaluated separately.
+3. Normalize each item into a bounded summary with source provenance and content-safety notes.
+4. Route ideation proposals through `strategy-planner`, `on-demand-brief-planner`, and `discord-approval-gate` before durable storage.
+
+## Source registry contract
+
+| Field | Decision |
+| --- | --- |
+| `source_kind` | `rss-feed` or `webpage`. |
+| `sensitivity` | `public-demo`, `public`, or `private-runtime`. |
+| `url_policy` | Git fixtures may use only fake/demo URLs such as `https://example.invalid/...`; private or production URLs stay outside the repo. |
+| `adapter_preference` | RSS uses a pending plugin spike; webpages prefer `web-readability`; search/fetch providers are optional discovery helpers. |
+| `storage_policy` | Raw source bodies and private URLs are not durable repo artifacts; only bounded summaries may become proposal inputs. |
+
+## Ingestion output contract
+
+Each source must produce a per-source status envelope before item normalization:
+
+- `source_ref` and `source_kind` must match the registered source, and `retrieved_by` must match its explicit `retrieval_adapter`;
+- `retrieval_mode` must remain `fake-fixture-no-network` in repo fixtures;
+- `status` is `succeeded`, `partial`, or `failed`;
+- `items_emitted` is bounded by `max_items_per_source`;
+- failed or partial sources include `failure_reason` and `isolated: true` so one inactive source does not block usable output from other sources;
+- `durable_write_executed` remains `false`.
+
+Each normalized item must include:
+
+- `item_id` stable within the ingestion batch;
+- `source_ref` pointing back to a registered source key, not a private raw URL;
+- `provenance` with `source_kind`, `retrieved_by`, `retrieval_mode`, `canonical_url`, and `source_title`, where kind and retrieval adapter match the registered source;
+- `summary` capped by `max_summary_chars`;
+- `ideation_signals` capped by `max_signals_per_item`;
+- `content_boundaries` declaring no raw dump, no private payload, and no durable write.
+
+## Planning and approval route
+
+Use ingestion output as proposal input only:
+
+```text
+source registry -> read-only adapter -> bounded summaries -> planning skill proposal -> discord approval gate -> optional durable write after approve write
+```
+
+Planning skills may map summarized signals into strategy slices or on-demand briefs. Any proposed update to `discord-project-manager/project/<project-slug>/strategy`, `content-ledger`, or `network/<network-slug>` remains `planned-only-until-approved` until the operator replies exactly `approve write`.
+
+## Adapter notes
+
+- RSS/feed ingestion: plugin choice remains a pending spike. Documented candidates in `docs/research/openclaw-runtime-capability-inventory.md` include `holo-rss-reader`, `@ipocket/clawrss`, and `@feednest/openclaw`.
+- Webpage ingestion: prefer the enabled Web Readability Extraction capability for article extraction where possible.
+- Search-backed discovery: DuckDuckGo, Exa, Firecrawl, Parallel, Perplexity, or SearXNG may be evaluated later as read-only discovery providers.
+- A Notion-backed source registry could be a future optional adapter, but this contract is storage-agnostic and does not depend on Notion.
+
+## Non-goals
+
+- No live fetching, plugin install/enable, Notion/API calls, publishing, scheduling, queue execution, or durable writes.
+- No private source URLs, credentials, Discord identifiers, raw source dumps, transcripts, or production claims in repo artifacts.
+- No claim that RSS polling, search providers, browser automation, or durable storage are wired by this issue.
+
+## Review checklist
+
+- [ ] Fixture includes at least one RSS feed source and one webpage source.
+- [ ] Every repo URL is fake/demo or intentionally public.
+- [ ] Every source has a status envelope, and partial or failed sources are isolated.
+- [ ] Output summaries are bounded and provenance-tagged.
+- [ ] Planning proposals use existing planning skills and `discord-approval-gate` before storage.
+- [ ] Validation runs without live network access.

docs/operations/discord-approval-responses.md

@@ -52,6 +52,16 @@ The fixture must cover:
 
 Memory-changing actions must ask for an explicit approval phrase. Do not treat silence, emoji reactions, or unrelated replies as approval.
 
+### Response-language policy
+
+Approval proposal prose must match the language of the current Discord message. Keep stable technical tokens in English: route names, namespaces, schema keys, and the exact approval phrase `approve write`. The option literals stay exactly:
+
+- `approve write`
+- `revise: <instruction>`
+- `reject`
+
+For Spanish operator messages, headings and explanatory labels should be Spanish, for example `Propuesta de actualización durable`, `Resumen del cambio`, `Límite de riesgo`, and `Respondé con exactamente una opción`.
+
 Recommended prompt shape:
 
 ```text
@@ -69,6 +79,29 @@ Reply with exactly one option:
 - reject
 ```
 
+Spanish prompt shape:
+
+```text
+user_message_language: es
+prose_reply_language: es
+technical_tokens_language: en
+language_policy: prose-matches-current-message; technical-tokens-stay-english
+
+Propuesta de actualización durable
+Route: <project>/<network>
+Runtime context: discord-project-manager/runtime/discord/<guild-id>/<channel-id>
+Target namespace: <namespace-key>
+Runtime audit namespace: discord-project-manager/runtime/discord/<guild-id>/<channel-id>
+Resumen del cambio: <resumen en español de una oración>
+Límite de riesgo: <qué no hace esta acción>
+Registro de auditoría: <resumen sanitizado o referencia audit_record>
+
+Respondé con exactamente una opción:
+- approve write
+- revise: <instruction>
+- reject
+```
+
 For content-ledger entries, include the ledger status:
 
 ```text