docs: the publish skill teaches stele amend, which now exists

[ProJedi1234]

Companion to stele-cli#5, which adds stele amend.

The problem

The document served at GET /skill — the one stele skill proxies verbatim into an agent's context — currently states:

stele has no rename command and no retime command, so neither is something you can do.

…along with "no command you can run will change it afterwards", "nothing you can run changes it once the page exists", and that a user wanting a rename "is asking for a newer stele".

All true when 570b375 shipped the route. All false once stele-cli#5 merges.

This is the same failure this document has already had once, running the other way: --ttl shipped in the client while the prose still read "stele publish does not expose this yet", so an agent refused a permanent page over a flag that already existed — and the refusal read as considered policy rather than a stale sentence. documentsEveryFlagTheAgentCanUse exists because of that incident. Leaving these sentences in place would have reproduced it verb for verb.

What changed

"Renaming a page, and changing its deadline" documents the command instead of its absence, leading with the two things an agent gets wrong by carrying over what it knows from publish:

• Omitting --ttl leaves the deadline alone, rather than applying the default — so a rename does not quietly put 7 days on a page somebody published to keep.
• Dropping --slug is not the escape from a 409 that it is on a publish: there it asks for a generated name, here it asks for no rename at all.

Plus the hard-move warning (kept verbatim, documentsThatRenamingReleasesTheOldName pins it), the commands table, the route table row, and the four scattered permanence claims.

minimumCLIVersion is deliberately not raised

Worth stating plainly, since it was considered and rejected. This file's own policy:

Raising it is a deliberate act that breaks every installed client older than the new value, so raise it when the wire contract actually moves — not when the CLI merely gains a feature.

A 0.2.0 client's wire behaviour is unchanged; it simply lacks a subcommand. Gating every write — including the publishes that still work perfectly — would be a disproportionate answer, and would break publishing on every machine in the field until each was reinstalled.

What an old client gets instead is now documented: stele amend fails with an unknown-command error carrying no exit code from the table, and the skill says outright that the fix is a reinstall rather than a rewording. That sentence is the entire mitigation, so the suite pins it.

This also keeps mentionsExactlyTheMinimumCLIVersion intact — the document still contains exactly one version string, the one in the 426 row.

Tests

documentsTheAmendRoute inverts: the assertions that pinned the absence of the command are the lie now, so they are replaced by ones pinning the command and the two inverted defaults.

doesNotClaimALifetimeIsUnchangeable grew a third time, and that is the interesting part. When the server learned to retime a page, every absolute claim became a claim about the client — "no command you can run" — honest for exactly as long as it was true. The client-scoped hedge is not a safer way to say it; it is the same claim with a shorter shelf life. Both spellings are in the sieve now.

One mechanical lesson recorded in CLAUDE.md: the markdown is a wrapped raw string, so an assertion phrase straddling a line break cannot be pinned at all. One of my new assertions failed exactly that way. Prose carrying an assertion gets reflowed to keep the claim on one line — not the reverse.

Also fixes SteleCLI.exits' code-5 remedy, a hand-checked transcription of the client's exit table that had drifted: "omit it and take a generated one" is advice stele amend cannot act on.

309 tests pass.

Merge order

⚠️ Merge after stele-cli#5, and ideally after 0.3.0 is installed where agents run. Between this merging and the client landing, the skill describes a command those binaries do not have — the reinstall sentence covers it, but the window is avoidable by ordering.

🤖 Generated with Claude Code

https://claude.ai/code/session_018qEtLbpPoxtUtucznPohMG

Summary by CodeRabbit

• Documentation
  • Documented the new stele amend command for renaming pages and changing deadlines.
  • Clarified that deadlines are preserved when omitted and can be updated while pages remain active.
  • Added guidance for expired or missing pages, name conflicts, required slugs, and resulting URLs.
  • Updated CLI references for publishing, amending, and direct API requests.
• Tests
  • Expanded documentation checks to cover amendment behavior and updated deadline guidance.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 6d836786-4e1c-4c67-a1f5-c5932f9684e9

📥 Commits

Reviewing files that changed from the base of the PR and between 570b375 and cde6a80.

📒 Files selected for processing (5)

• CLAUDE.md
• README.md
• Sources/SteleCore/PublishSkill.swift
• Sources/SteleCore/SteleCLI.swift
• Tests/SteleCoreTests/PublishSkillTests.swift

---

📝 Walkthrough

Walkthrough

The PR documents stele amend, including renaming, deadline changes, preserved deadlines, conflicts, and expired pages. It updates CLI guidance, README command mappings, and tests that validate the publish skill.

Changes

Amend command documentation

Layer / File(s)	Summary
Command and route guidance README.md, Sources/SteleCore/SteleCLI.swift	The README maps CLI commands to HTTP writes. CLI exit code 5 guidance now distinguishes publish from amend.
Amendment semantics in the publish skill Sources/SteleCore/PublishSkill.swift	The skill documents amend parameters, deadline preservation, retiming, renaming, conflicts, expired pages, route mapping, and URL behavior.
Documentation test and authoring checks Tests/SteleCoreTests/PublishSkillTests.swift, CLAUDE.md	Tests require amend documentation and reject outdated lifetime-immutability claims. Authoring guidance requires matching assertions and single-line wrapped strings.

Estimated code review effort: 2 (Simple) | ~10 minutes

Poem

A rabbit hops through docs so bright,
stele amend now sets things right.
Deadlines move, names may change,
Old links retire within their range.
Tests guard each written line.

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands.}