axstack 0.38.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/host-operations.md

@@ -235,15 +235,24 @@ This opt-in script changes only root `defaultModelSelection` in
 `~/.t3/userdata/settings.json`. Without a pool it changes only the instance
 among enabled accounts of the current Claude/Codex driver.
 `AXSTACK_SYNC_POOL` compares drivers by weekly clocks (>=604800s), without
-plan weights. Rotation needs a ten-point elapsed-minus-used pace lead;
-excluded/unauthorized/skipped current accounts can escape to known candidates.
-Any window at 95% or a reached limit excludes. Non-current absent credentials
+plan weights. Weekly remaining quota is `R = 100 - used` for the selected
+weekly window. Prefer the highest band: `R >= 15`, `10 <= R < 15`, then `R < 10`.
+A higher band switches without a pace margin; within the same band, rotation
+needs a ten-point elapsed-minus-used pace lead and the current account wins ties.
+This also applies when every eligible account is below 10% remaining: known
+usable quota stays usable, ranked by pace. Without a pool, only pace applies.
+This is a best-effort weekly reserve preference, not a guaranteed budget for
+future work. The current hard guard still excludes any window at 95% used
+or a reached limit. Excluded/unauthorized/skipped current accounts can escape
+to known candidates before the unknown hold; otherwise any unknown holds,
+even below 10% remaining. No eligible candidate leaves the default untouched.
+Non-current absent credentials
 exclude; malformed/unreadable credentials and unknown/stale usage hold.
 Cache expires after five minutes. Missing defaults stay untouched; OAuth tokens
 are never refreshed. Each host's pool uses only enabled, credentialed drivers:
 
 ```sh
-AXSTACK_SYNC_POOL=claudeAgent=claude-opus-5-5,codex=gpt-6.1-sol:xhigh \
+AXSTACK_SYNC_POOL=claudeAgent=claude-opus-5-5,codex=gpt-6-astra:medium \
   bun ~/.agents/skills/axstack/scripts/sync-default.js --dry-run
 ```
 
@@ -258,6 +267,15 @@ A fsynced sibling preserves mode; original bytes are checked before rename and
 read back afterward. The accepted sub-ms T3 write race can lose an edit;
 read-back mismatch is an error.
 
+Validate pool models and efforts against each host's catalog before activation.
+Preserve that host's current Opus effort by including it explicitly when set;
+the illustrative Claude entry above omits effort. If the current Codex default
+still uses Sol, the driver performs a one-time same-account selection migration
+to `gpt-6-astra:medium` during authorized host activation, saving rollback bytes
+and verifying the write/readback. The helper does not enforce models when the
+account stays selected. Only new chats use the changed default; running threads,
+role routing, schedules and `roles.json` stay outside this policy.
+
 Under host-mutation authority, install and enable:
 
 ```sh
@@ -277,7 +295,7 @@ Override Bun/skills paths via `ExecStart`/`Environment` in
 
 ```ini
 [Service]
-Environment=AXSTACK_SYNC_POOL=claudeAgent=claude-opus-5-5,codex=gpt-6.1-sol:xhigh
+Environment=AXSTACK_SYNC_POOL=claudeAgent=claude-opus-5-5,codex=gpt-6-astra:medium
 ```
 
 Reload after edits. Logout needs authorized linger; installation never activates units.

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.38.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/scripts/sync-default.js

@@ -39,17 +39,21 @@ export function decide(settings, usage, now, pool = null) {
       && Number.isFinite(window?.used) && Number.isFinite(window?.seconds) && window.seconds > 0
       && Number.isFinite(window?.resetAt) && window.resetAt > now
       && (!pooled || window.seconds >= 604800);
+    const remaining = known ? 100 - window.used : null;
     return { instanceId, state: excluded ? 'excluded' : known ? 'eligible' : 'unknown',
+      ...(pooled && { band: known ? remaining >= 15 ? 2 : remaining >= 10 ? 1 : 0 : null }),
       pace: known ? 100 * (1 - (window.resetAt - now) / (window.seconds * 1000)) - window.used : null };
   });
   const current = result.instances.find((entry) => entry.instanceId === from);
-  const best = result.instances.filter((entry) => entry.state === 'eligible').sort((a, b) => b.pace - a.pace)[0];
+  const best = result.instances.filter((entry) => entry.state === 'eligible')
+    .sort((a, b) => (pooled ? b.band - a.band : 0) || b.pace - a.pace)[0];
   const excluded = !current || current.state === 'excluded';
   if (excluded && best) return updated(best, 'current-excluded');
   if (result.instances.some((entry) => entry.state === 'unknown')) return { ...result, reason: 'unknown' };
   if (!best) return { ...result, reason: 'no-eligible' };
-  if (best.instanceId !== from && best.pace - current.pace >= 10) {
-    return updated(best, 'pace');
+  const higherBand = pooled && best.band > current.band;
+  if (best.instanceId !== from && (higherBand || best.pace - current.pace >= 10)) {
+    return updated(best, higherBand ? 'reserve' : 'pace');
   }
   return { ...result, reason: 'margin' };
 }

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.