docs: report a bug or request a feature from the conversation

docs/api.html

@@ -447,6 +447,25 @@ <h2 id="conversation-deletion">Delete a conversation</h2>
 <p><code>409</code> returns <code>{ deleted: false, decision: { kind: "refused", say } }</code>, explaining what was kept and what to do next. Unfinished, paused or uncertain tasks, running turns, background work and widget actions still settling block deletion. Finish, cancel or reconcile that work before trying again.</p>
 <p>Saved memory, independent resources, session logs and append-only audit/replication history are kept. After confirmed success, the app starts a fresh conversation. If the network reply is lost, the result is unknown: reload before retrying.</p>
 
+<h2 id="product-reports">Report a bug or request a feature</h2>
+<p>The routes behind <a href="./#report"><code>/report</code></a>. Reports go only to the canonical repository <code>digitopvn/clarkcant</code>: the target comes from the node's trusted configuration, and no request field can change it.</p>
+<div class="table-wrap" tabindex="0"><table>
+  <thead><tr><th>Method</th><th>Path</th><th>Body</th><th>Answer</th></tr></thead>
+  <tbody>
+    <tr><td>POST</td><td><code>/feedback/reports</code></td><td><code>{ request, conversationId? }</code></td><td><code>201 { draft, diagnostics }</code>. Prepares and keeps a draft; nothing is filed.</td></tr>
+    <tr><td>GET</td><td><code>/feedback/reports/{reportId}</code></td><td>–</td><td><code>{ draft, status, publication? }</code></td></tr>
+    <tr><td>POST</td><td><code>/feedback/reports/{reportId}/publish</code></td><td><code>{ conversationId, intent?: "send" | "check" | "send-anyway", answers? }</code></td><td><code>{ publication, eligibility?, messageId, timeline }</code>, with the result card written into the conversation. Person-only.</td></tr>
+  </tbody>
+</table></div>
+<p><code>request</code> is <code>{ kind: "bug" | "feature", description, source, includeDiagnostics?, title?, subsystem?, bug?, feature?, evidence?, error?, philosophy? }</code>, where <code>source</code> is <code>slash</code>, <code>chat</code>, <code>voice</code> or <code>composer</code>. Sections nobody spoke to are left out of the issue. A feature carries a philosophy fit (<code>aligned</code>, <code>aligned-with-constraints</code> or <code>material-conflict</code>); a conflict is still filed as asked.</p>
+<p>Publishing is the person's own press, so the WebSocket relay, MCP and <code>clarkcant api</code> refuse it with <code>403 PERSON_ONLY</code>. The write is an <code>external-write</code> effect and the execution policy applies to it. <code>intent</code> defaults to <code>send</code>; <code>answers</code> names the card the press was on, so that card reads as used from then on.</p>
+<ul>
+  <li><code>publication.status</code> is <code>published</code> (<code>mode</code> <code>created</code> or <code>commented</code>) only after GitHub is read back holding the report's hidden marker. The other statuses are <code>unknown</code>, <code>failed</code>, <code>needs-access</code> (no <code>github_token</code>; carries <code>manualUrl</code>, GitHub's prefilled new-issue page) and <code>refused</code>.</li>
+  <li><code>intent: "check"</code> only looks for the marker and never sends; checking a report never sent answers <code>409 NOTHING_SENT</code>. Once GitHub shows the marker absent at least two minutes after the attempt, the report becomes <code>failed</code> with <code>retryable</code>, and sending it again files it for the first time.</li>
+  <li>When checking cannot settle it, the report stays <code>unknown</code> with <code>inconclusive: { since, searchUrl, manualUrl }</code>. Only then is <code>intent: "send-anyway"</code> accepted (otherwise <code>409 NOT_INCONCLUSIVE</code>), and it may file the report twice.</li>
+  <li>A published report carries <code>eligibility</code>: whether Clark may handle the issue. In this build it is always <code>eligible: false</code> with <code>code: "handling-unavailable"</code>.</li>
+</ul>
+
 <h2 id="widget-files">Files a widget holds</h2>
 <p>A widget never gets a path. It holds a file as an <code>artifactRef</code>, <code>{ v, artifactId, kind, mimeType, sizeBytes, name, digest? }</code>, and your machine checks the widget's grant again every time the ref is used, so a ref copied elsewhere opens nothing. A grant lasts 24 hours from the pick or the widget's last write. After that a widget still reads a file it made and finished, while a file the person chose has to be chosen again. A file still being written is removed 24 hours after its last write. One file is at most 25 MiB, and one widget keeps at most 128 MiB of your 1 GiB. That share counts the files the widget made and what it attached from them, but not the files you chose for it. A widget can discard only a file it made. Every answer is a ref, bytes, or a refusal whose code says what was wrong. A file's name goes out as both <code>filename</code> and <code>filename*</code> (RFC 6266), so a name with accents downloads as it was written.</p>
 <p><a href="#conversation-deletion">Deleting the conversation</a> releases its widget files and grants, including finished files never attached. Shared bytes stay; physical cleanup waits for the database commit.</p>

docs/index.html

@@ -95,9 +95,18 @@ <h2 id="slash-commands">Slash commands</h2>
   <li><code>/logout</code> signs out of a provider whose key Clark stored. If a key comes from the environment, such as <code>.env</code> or the shell, the card says so and you remove it there.</li>
   <li><code>/thinking</code> chooses how hard the next turns think, from a list, or directly: <code>/thinking high</code>, <code>/thinking default</code>. It is the same setting as Settings → AI &amp; Routing → Thinking level.</li>
   <li><code>/background &lt;request&gt;</code> runs the request as background work beside the conversation and reports back in it.</li>
+  <li><code>/report</code> reports a bug or asks for a feature in ClarkCant itself. See <a href="#report">below</a>.</li>
 </ul>
 <p>A command typed in the middle of a sentence is just text. Commands are not sent to the model. See <a href="api.html#provider-sign-in">provider sign-in routes</a>.</p>
 
+<h2 id="report">Report a bug or request a feature</h2>
+<p>Type <code>/report</code> to get a card where you choose Bug or Feature, say what happened or what you want in your own words, and open “What will be shared” to see exactly what goes with it. <code>/report bug …</code> and <code>/report feature …</code> (also <code>lỗi</code> and <code>tính năng</code>), a sentence to Clark, or your voice go one step further: Clark prepares the report and shows the issue exactly as it would be filed. None of these sends anything. Only your own press on <strong>Create issue</strong> files the report; Clark, its tools and voice cannot. Reports go to <a href="https://github.com/digitopvn/clarkcant" rel="noopener"><code>digitopvn/clarkcant</code></a> and nowhere else.</p>
+<p>Your execution policy applies to that press. If it denies the action, the report is refused and nothing is sent; if it would ask first, your press is the answer. Before filing, Clark looks through open issues and issues closed in the last 90 days, and when an open issue clearly matches, your report is added to it as a comment instead of opening another.</p>
+<p>The result card says which way it went: <strong>Issue opened</strong> or <strong>Added to an existing issue</strong> (only once Clark has read the report back from GitHub), <strong>Outcome not known yet</strong>, <strong>Not filed</strong>, <strong>GitHub access needed</strong> or <strong>Refused by your policy</strong>. When GitHub's answer never arrived, <strong>Check again</strong> only looks; it never sends. <strong>Send again</strong> appears only once GitHub shows the report missing at least two minutes after the attempt. If Clark cannot tell whether GitHub kept it, the card says so, links the issues you opened since then and a prefilled new-issue page, and offers <strong>Send anyway</strong>, which may file it twice. Clark never sends a report again on its own: after a restart, reports left unsettled are checked, not resent, and the result is posted in their conversation.</p>
+<p>Filing uses the GitHub token (<code>github_token</code>) you stored for signal sources. Without one, the card shows GitHub access needed with a link to GitHub's new-issue page, already filled in, so you can file it yourself. The repository also has Bug report and Feature request issue templates for filing by hand.</p>
+<p class="note"><strong>What is shared, and what never is.</strong> Your words, with secrets redacted, and safe diagnostics unless you turn them off: the ClarkCant version, OS and architecture, runtime, locale and input mode, the part of ClarkCant it is about, the provider and model, and an error as a short redacted excerpt with a fingerprint. Never sent: the conversation, system prompts, files, environment variables, raw logs or credentials. Your home folder is written as <code>~</code>, and <code>@mentions</code> in your words are neutralised so a report notifies nobody.</p>
+<p>Asking Clark to work on an issue you filed is not available yet; the result card says why. See the <a href="api.html#product-reports">report routes</a>.</p>
+
 <h2 id="inbox">Inbox and notifications</h2>
 <p>Open the inbox from its header badge, with the keyboard, or by asking Clark in text or voice: “open the inbox”. It brings together command approvals, package permissions, approvals a running task raised, open questions and stored notices about background work, expired requests and available updates. Clark's <code>control_app</code> tool reaches the same inbox.</p>
 <p>Granting an approval raised by a running task lets the node run it again; if the node cannot accept the run, Clark says nothing has run and you can ask again. Denial or expiry ends the task. That decision belongs to you; machine interfaces refuse it. See <a href="api.html#waiting-approvals">task approval decisions</a>.</p>

docs/mcp.html

@@ -107,7 +107,7 @@ <h2 id="tools">Tools</h2>
     <tr><td><code>act_on_notice</code></td><td><code>{ noticeId, action, until? }</code></td><td>Same as <a href="api.html#notice-action-route"><code>POST /inbox/notices/{noticeId}/actions/{action}</code></a>: marks a notice read or unread, dismisses it or undoes the dismissal within five minutes (<code>restore</code>), snoozes (<code>until</code>) or brings it back, quiets its kind or turns it back on, runs failed work again, skips a version or asks an expired question again. Your node checks the action against what the notice offers now and changes nothing when it refuses. Installing an update is not offered: it is yours to press on the notice, and your node refuses it from MCP with <code>PERSON_ONLY</code>.</td></tr>
   </tbody>
 </table></div>
-<p class="note"><strong>No approval tool, on purpose.</strong> A person's decisions (approving a guarded action, deciding a package capability, confirming an app intent, reporting what the app did with an action the agent asked for, trusting a paired peer or issuing a grant) stay on the person's own surfaces, and MCP, the WebSocket and <code>clarkcant api</code> refuse them with <code>403 PERSON_ONLY</code>. An AI client must not be able to approve its own action or widen its own trust. Exporting a table from the conversation as a CSV file is refused on the same relays: the file is written for the person looking at the table, not handed to a machine client. Saving a widget's file with Save As, and handing a widget a file the person chose, are refused the same way. Stop, answering a question and reading stay available; the discovery document lists these routes under <code>personDecisions</code>.</p>
+<p class="note"><strong>No approval tool, on purpose.</strong> A person's decisions (approving a guarded action, deciding a package capability, confirming an app intent, reporting what the app did with an action the agent asked for, trusting a paired peer or issuing a grant) stay on the person's own surfaces, and MCP, the WebSocket and <code>clarkcant api</code> refuse them with <code>403 PERSON_ONLY</code>. An AI client must not be able to approve its own action or widen its own trust. Exporting a table from the conversation as a CSV file is refused on the same relays: the file is written for the person looking at the table, not handed to a machine client. Saving a widget's file with Save As, and handing a widget a file the person chose, are refused the same way. Filing a <a href="api.html#product-reports">product report</a> on GitHub is refused the same way: only the person's own Create issue press files one. Stop, answering a question and reading stay available; the discovery document lists these routes under <code>personDecisions</code>.</p>
 
 <h2 id="raw">Raw JSON-RPC</h2>
 <p>MCP clients do this for you. To see the wire format, or to call the tools from a script:</p>

vi/docs/api.html

@@ -447,6 +447,25 @@ <h2 id="conversation-deletion">Xoá hội thoại</h2>
 <p><code>409</code> trả về <code>{ deleted: false, decision: { kind: "refused", say } }</code>, giải thích cái gì được giữ và bước tiếp theo. Task chưa kết thúc, đang tạm dừng hoặc chưa rõ kết quả, lượt trả lời, công việc nền và thao tác widget còn đang xử lý kết quả đều chặn việc xoá. Hãy hoàn tất, huỷ hoặc đối soát công việc đó rồi thử lại.</p>
 <p>Bộ nhớ đã lưu, tài nguyên độc lập, nhật ký phiên và lịch sử kiểm toán/đồng bộ chỉ ghi thêm được giữ lại. Sau khi xác nhận thành công, ứng dụng bắt đầu hội thoại mới. Nếu mất phản hồi mạng thì chưa rõ kết quả: tải lại trước khi thử lại.</p>
 
+<h2 id="product-reports">Báo lỗi hoặc đề xuất tính năng</h2>
+<p>Các route phía sau <a href="./#report"><code>/report</code></a>. Báo cáo chỉ tới repo chuẩn <code>digitopvn/clarkcant</code>: đích đến lấy từ cấu hình tin cậy của node, và không trường nào trong yêu cầu đổi được nó.</p>
+<div class="table-wrap" tabindex="0"><table>
+  <thead><tr><th>Method</th><th>Path</th><th>Body</th><th>Phản hồi</th></tr></thead>
+  <tbody>
+    <tr><td>POST</td><td><code>/feedback/reports</code></td><td><code>{ request, conversationId? }</code></td><td><code>201 { draft, diagnostics }</code>. Chuẩn bị và lưu bản nháp; chưa gửi gì.</td></tr>
+    <tr><td>GET</td><td><code>/feedback/reports/{reportId}</code></td><td>–</td><td><code>{ draft, status, publication? }</code></td></tr>
+    <tr><td>POST</td><td><code>/feedback/reports/{reportId}/publish</code></td><td><code>{ conversationId, intent?: "send" | "check" | "send-anyway", answers? }</code></td><td><code>{ publication, eligibility?, messageId, timeline }</code>, kèm thẻ kết quả ghi vào cuộc trò chuyện. Chỉ người dùng.</td></tr>
+  </tbody>
+</table></div>
+<p><code>request</code> là <code>{ kind: "bug" | "feature", description, source, includeDiagnostics?, title?, subsystem?, bug?, feature?, evidence?, error?, philosophy? }</code>, trong đó <code>source</code> là <code>slash</code>, <code>chat</code>, <code>voice</code> hoặc <code>composer</code>. Phần nào không ai nói tới thì bị bỏ khỏi issue. Đề xuất tính năng kèm mức phù hợp triết lý (<code>aligned</code>, <code>aligned-with-constraints</code> hoặc <code>material-conflict</code>); yêu cầu xung đột vẫn được gửi đúng như đã nói.</p>
+<p>Gửi báo cáo là cú bấm của chính người dùng, nên relay WebSocket, MCP và <code>clarkcant api</code> từ chối bằng <code>403 PERSON_ONLY</code>. Lần ghi là một hiệu ứng <code>external-write</code> và policy thực thi áp dụng cho nó. <code>intent</code> mặc định là <code>send</code>; <code>answers</code> nêu thẻ mà cú bấm nằm trên, để từ đó thẻ ấy hiện là đã dùng.</p>
+<ul>
+  <li><code>publication.status</code> chỉ là <code>published</code> (<code>mode</code> là <code>created</code> hoặc <code>commented</code>) sau khi đọc lại GitHub và thấy dấu ẩn của báo cáo. Các trạng thái khác là <code>unknown</code>, <code>failed</code>, <code>needs-access</code> (chưa có <code>github_token</code>; kèm <code>manualUrl</code>, trang tạo issue của GitHub đã điền sẵn) và <code>refused</code>.</li>
+  <li><code>intent: "check"</code> chỉ tìm dấu và không bao giờ gửi; kiểm tra một báo cáo chưa từng gửi trả <code>409 NOTHING_SENT</code>. Khi GitHub cho thấy không có dấu ít nhất hai phút sau lần thử, báo cáo chuyển thành <code>failed</code> kèm <code>retryable</code>, và gửi lại là gửi nó lần đầu tiên.</li>
+  <li>Khi việc kiểm tra không thể ngã ngũ, báo cáo vẫn là <code>unknown</code> kèm <code>inconclusive: { since, searchUrl, manualUrl }</code>. Chỉ khi đó <code>intent: "send-anyway"</code> mới được nhận (nếu không thì <code>409 NOT_INCONCLUSIVE</code>), và nó có thể gửi báo cáo hai lần.</li>
+  <li>Báo cáo đã gửi kèm <code>eligibility</code>: Clark có được tự xử lý issue hay không. Trong bản này nó luôn là <code>eligible: false</code> với <code>code: "handling-unavailable"</code>.</li>
+</ul>
+
 <h2 id="widget-files">Tệp mà một widget giữ</h2>
 <p>Widget không bao giờ nhận được đường dẫn. Nó giữ một tệp dưới dạng <code>artifactRef</code>, <code>{ v, artifactId, kind, mimeType, sizeBytes, name, digest? }</code>, và máy của bạn kiểm lại quyền của widget mỗi lần ref được dùng, nên một ref bị chép sang chỗ khác không mở được gì. Một quyền kéo dài 24 giờ kể từ lúc chọn tệp hoặc lần ghi gần nhất của widget. Sau đó, widget vẫn đọc được tệp do chính nó tạo và đã hoàn tất, còn tệp người dùng đã chọn thì phải được chọn lại. Một tệp còn đang ghi dở bị xoá 24 giờ sau lần ghi gần nhất. Mỗi tệp tối đa 25 MiB, và mỗi widget giữ tối đa 128 MiB trong 1 GiB của bạn. Phần đó tính các tệp widget đã tạo và những gì nó đính kèm từ các tệp ấy, nhưng không tính các tệp bạn đã chọn cho nó. Widget chỉ bỏ được tệp do chính nó tạo. Mọi câu trả lời là một ref, các byte, hoặc một lời từ chối có mã nói rõ điều gì sai. Tên tệp được gửi đi dưới cả hai dạng <code>filename</code> và <code>filename*</code> (RFC 6266), nên một tên có dấu được tải xuống đúng như khi viết.</p>
 <p><a href="#conversation-deletion">Xoá hội thoại</a> giải phóng tệp widget và grant của nó, kể cả tệp đã hoàn tất nhưng chưa đính kèm. Byte dùng chung được giữ; việc dọn tệp vật lý chờ database commit.</p>