axstack 0.39.0 → 0.40.0

package/README.md

@@ -66,7 +66,7 @@ You make decisions at holds and substantial-spec approval.
 Follow [getting started](docs/getting-started.md) for the full first-task journey
 and [guides](docs/guides.md) for features, reviews, watches, debugging and releases.
 
-## What you can do (19 skills)
+## What you can do (20 skills)
 
 | Layer | Skill | What it does |
 | --- | --- | --- |
@@ -85,6 +85,7 @@ and [guides](docs/guides.md) for features, reviews, watches, debugging and relea
 | Operate | [axstack-watch](skills/axstack-watch/SKILL.md) | Observe or maintain an existing PR within its authority. |
 | Operate | [axstack-cleanup](skills/axstack-cleanup/SKILL.md) | Retire eligible completed agent resources. |
 | Operate | [axstack-relay](skills/axstack-relay/SKILL.md) | Send an explicit message or authorized notification. |
+| Operate | [axstack-publish](skills/axstack-publish/SKILL.md) | Publish one checked Explain article in the explicitly authorized private or public mode. |
 | Understand | [axstack-research](skills/axstack-research/SKILL.md) | Answer one bounded question with sources. |
 | Understand | [axstack-scout](skills/axstack-scout/SKILL.md) | Gather codebase evidence for an agent across several areas. |
 | Understand | [axstack-explain](skills/axstack-explain/SKILL.md) | Explain a system and separate known behavior from gaps. |

package/docs/workflows.md

@@ -22,6 +22,9 @@ immediately before dispatch or account re-selection.
 
 Direct routes need no spec ceremony:
 
+- [axstack-publish](../skills/axstack-publish/SKILL.md) publishes one Explain
+  HTML article in one explicitly authorized private or public mode through the
+  driver, after final-byte checks, independent review and live verification.
 - [axstack-verify](../skills/axstack-verify/SKILL.md) routes verification-skill
   creation and maintenance through Implement.
   A single-behavior check uses an existing `verify-<app>` skill or UI verification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Axstack installer and setup CLI: installs owned chat skills and role data, configures supported harness settings, and checks T3 Code capabilities.",
   "keywords": [
     "claude-code",

package/skills/axstack-publish/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: axstack-publish
+description: When the user requests publication of an Explain HTML article, use axstack-publish to verify and publish that article in the explicitly authorized mode.
+---
+
+# Publish
+
+Publish an existing Explain HTML article through the notes CLI on the configured publish host.
+The current T3 driver owns publication; workers return checked artifacts.
+Load [Standing contracts](../axstack/references/contracts.md) and follow its
+lifecycle pointers. Keep page bytes, checks and receipts in private run evidence.
+
+## 1. Bind the request
+
+Read host-managed `~/.config/axstack/publish.json` containing string fields
+`sshHost`, `publicOrigin` and `docsOrigin`.
+
+```json
+{"sshHost":"<publish host>","publicOrigin":"<public HTTPS origin>","docsOrigin":"<docs HTTPS origin>"}
+```
+
+Validate `sshHost` as `^[A-Za-z0-9][A-Za-z0-9.-]*$` and both origins as HTTPS
+URL origins with no credentials, path, query or fragment.
+Hold publication if the config is missing or invalid.
+Never guess a publish host or either origin.
+Keep these routing values host-managed; this config grants no publication authority.
+Identify the Explain page by its exact bytes, byte count and SHA-256.
+State the article, slug, mode (`private` or `public`) and target URL.
+Public targets `<publicOrigin>/<slug>/`; private targets the
+SlashDocs document URL at `docsOrigin` returned by the CLI.
+For a new private document, state that origin and slug before publication and
+record the allocated URL afterwards.
+Require explicit authority for exactly one article and one mode per request.
+Promotion, unpublish, reader changes and grant changes each need their own request.
+Local creation or an earlier publication supplies no new publication authority.
+If the request leaves the article or mode unclear, hold publication for clarification.
+
+## 2. Prepare the final artifact
+
+For public mode, run the [Explain redaction check](../axstack-explain/SKILL.md#3-verify-and-deliver)
+to remove private paths, IDs, credentials, prompts, messages and internal records.
+For public mode, run Explain's [self-contained asset check](../axstack-explain/references/inline-pages.md#check-the-exact-bytes).
+Reuse Explain's [page rules](../axstack-explain/references/inline-pages.md#page-rules)
+and [Visual QA](../axstack-explain/references/visual-qa.md) for checks and verifier routing.
+
+Add a standalone light/dark theme with inline defaults and `prefers-color-scheme`
+so the article works outside T3; honor an explicit user theme request.
+Theme adaptation changes bytes: save `final.html`, its byte count and SHA-256,
+then rerun the referenced Explain page checks on these final bytes.
+Require a fresh independent `axstack-explainer-review` on the final bytes.
+Preview these exact bytes with Playwright MCP at 728px dark and 360px light;
+record both screenshots and the Explain QA results.
+Any subsequent byte change invalidates checks and review: repeat this step.
+Hold publication while any required check or review is missing or failed.
+
+## 3. Publish from the driver
+
+Publish only from the driver thread.
+Use stdin only with no TTY and at most
+5,000,000 bytes (5 MB) of final HTML:
+
+```bash
+ssh <publish host> notes publish --mode <mode> --slug <slug> < final.html
+```
+
+Use the validated `sshHost`, validate the slug as `^[a-z0-9][a-z0-9-]{0,63}$`
+and select one literal mode (`private` or `public`).
+Use safely quoted arguments, never interpolate unchecked input into a shell.
+Require exit zero and one JSON line containing `url`, `doc`, `version`, `sha256`.
+Compare its SHA with the final artifact; a mismatch or ambiguous result holds
+success reporting until reconciled with `ssh <publish host> notes status --slug <slug>`.
+Require the returned URL's origin to match the configured origin for that mode.
+Retain phase errors and pending state as unresolved evidence.
+
+## 4. Prove the live result and return
+
+Verify the live URL in a real browser using Playwright MCP against the final SHA-256.
+For public mode, verify an anonymous browser reads exact response bytes at
+`<publicOrigin>/<slug>/` whose SHA-256 matches the final artifact.
+Hash the response body bytes, rather than DOM serialization or rendered text.
+For private mode, verify anonymous navigation reaches the SlashDocs sign-in page
+leading to Dex and `notes status --slug <slug>` reports `published: true`, the
+live version and SHA-256 that matches the final bytes.
+Compare status's private version with the publish result; null live metadata
+or a pending operation leaves verification unproven.
+Reader-side reads are proven only by the separately authorized AC23 end-to-end
+run; an anonymous redirect and CLI metadata do not prove a reader grant.
+Return URL, version and SHA-256 with the live verification evidence or its hold.
+Tell the user when `overwrote_external_edit` is true: publication replaced an
+external edit, retained as an earlier SlashDocs version.
+
+Agents never handle reader passwords.
+Agents never run `notes reader show` or allocate a TTY (`-t` or `-tt` on SSH).
+Reader and grant commands require their own request and secret-free non-TTY output.
+The owner shares reader credentials separately from the article link.