mirror of
https://github.com/pollen-robotics/microduck.git
synced 2026-11-22 09:38:03 +08:00
* docs: a README a robot user can actually start from
The README was four documents in one — pitch, dev setup, board operations
manual, dev-key plumbing, release process and status — at 457 lines. Someone
handed a robot met `robotctl monitor`'s projected-gravity paragraph before
learning how to make the thing move.
Most people joining will use the robot, not develop the shipping machinery.
So the README is now the first hour for that reader: is it alive, drive it
with a gamepad, watch the loop, run your own .onnx, put a branch on it. The
padd socket-forward recipe — pad on your laptop, robot on the bench, nothing
cross-compiled — was buried in a source comment and is now the centrepiece.
Everything else moves rather than disappears:
docs/install-dev.md new: the linear dev-board install, split out of
deploy/README.md, which stays as the reference for
what those steps do. Leaves a slot for the
regular-user install doc.
CONTRIBUTING.md new: building, testing, layout, conventions,
releasing — the daemon-developer door.
docs/cheatsheet.md absorbs monitor, completions, update log, and
select/pin/reset-to-golden with the three
easy-to-get-wrong notes.
Services and status were duplicated in architecture.md §1 and roadmap.md, so
they are links now rather than a third copy.
padd ships in the release but only robotctl gets a PATH symlink
(scripts/install.sh:633), so the on-robot invocation is the full path.
Assisted-by: Claude:claude-opus-5[1m]
* docs: drop self-referential commentary from the front docs
A doc that describes itself spends the reader's attention on navigation
rather than on the robot. Cut the paragraph telling the reader what the
README covers, the 'shorter door' framing, and the repeated 'read it
when' stems in the link table.
Assisted-by: Claude:claude-opus-5[1m]
* docs: plainer opening, and defer the dev-install prerequisite to its own page
The socket path and the wire format are not what a reader needs in the
first two lines; robotctl being the thing you talk to is. The branch
section likewise only needs to say the dev install is a prerequisite,
not re-explain what it consists of.
Assisted-by: Claude:claude-opus-5[1m]
* Update README.md
* Update README.md
* docs: basic update commands in the README, health contract where tools need it
The README jumped from watching the robot straight to installing branch
builds, with no answer for someone who only wants the current release.
The health rationale that came out of the README lands in architecture
§8.4, next to the version discussion it belongs beside, and the exit-code
contract is repeated in the cheat sheet where anyone scripting will look.
Assisted-by: Claude:claude-opus-5[1m]
* docs: explain apply-without-ref where the command is introduced
The warning sat two sections below the command it was about, so the
reader met the plain form first and the caveat only if they carried on
into branch builds. Stating what the stable channel means at the point
of use leaves the branch section to say what --ref adds.
Assisted-by: Claude:claude-opus-5[1m]
* docs: move the policy tensor contract into robotd-design
Tensor widths and the legacy 51-D refusal are what you need when a
policy will not load, not when you are swapping one in. They join the
rest of the load-time validation in §5.3, and the params file outliving
an update joins §7.2, which is already about that file's lifetime.
Assisted-by: Claude:claude-opus-5[1m]
* docs: dev-channel mechanics out of the README
Tag movement and version uniqueness join the --ref explanation in the
cheat sheet; the trust argument for dev builds joins install-dev, where
the reader is deciding to trust that key. 'A merge does not publish
instantly' was already in the cheat sheet, so the README keeps only the
short form.
Assisted-by: Claude:claude-opus-5[1m]
* docs: branch workflow as steps
Assisted-by: Claude:claude-opus-5[1m]
* docs: trim the update section to the commands
Assisted-by: Claude:claude-opus-5[1m]
* docs: group by audience — robot, design, project
Ten docs sat flat in docs/, so a design doc, a runbook and an open
post-mortem all looked equally authoritative. install-path-gap.md reads
as current architecture until you notice the Status line.
robot/ cheatsheet, install-dev — you have a robot
design/ architecture and the three — you are changing the daemon
design docs
project/ roadmap, ci-setup, and the — dated records, stale on
two records purpose
docs/README.md indexes all three. deploy/README.md stays next to the
config files it documents. Every cross-link repointed and checked.
Assisted-by: Claude:claude-opus-5[1m]
* docs: split the cheat sheet by audience, dedupe the deploy quickstart
The cheat sheet was 435 lines serving two readers: robotctl on a robot,
and btctl plus the dev channel, which need a clone and a dev board.
Split at that line — cheatsheet.md is the robot, cheatsheet-dev.md is
the dev board. 'Building and checking' was neither, so it joins the
build commands in CONTRIBUTING.
deploy/README.md kept a full copy of the dev-board provisioning walk-
through that install-dev.md now owns. It keeps the two commands and the
flags, and defers the rest.
Where next is now two groups rather than six flat rows: going further
with a robot, and contributing.
Assisted-by: Claude:claude-opus-5[1m]
* ci: follow the docs move when packaging a release
dev.yml and release.yml ship architecture.md and updater-design.md
inside the artifact, by source path. The move to docs/design/ broke
packaging on every push. The destination inside the release is
unchanged, so nothing on a board moves.
Assisted-by: Claude:claude-opus-5[1m]
* docs: repoint doc paths in comments after the move, and note --help in the README
Around ninety source comments cite docs/<name>.md by path. They break
nothing, but a path that does not resolve teaches the reader to stop
trusting the next one. Includes the rustdoc intra-doc links in
updater/src/lib.rs.
The README now says robotctl explains itself, so the commands can be
explored rather than looked up.
Assisted-by: Claude:claude-opus-5[1m]
* docs: start install-dev at flashing the board
The doc began at 'a board you can reach over ssh', which is several
steps in. Name the image and the imager profile, since setting wifi and
the user there is what makes the board reachable without a serial
console.
Assisted-by: Claude:claude-opus-5[1m]
* deploy: commit the team dev key, outside trusted_keys/
Keeping team.dev.pub out of the repository protected nothing. A board
accepts dev builds only when the key is in its own trusted_keys_dir and
allow_dev_keys is true, and signing a build needs the private half,
which has not moved. What the absence did buy was a round trip for
every new developer, asking someone for a file.
It goes in deploy/dev-key/ rather than deploy/trusted_keys/, because
install.sh copies the latter onto every robot and this must reach only
boards that opt in. provision-board.sh now falls back to the committed
copy when ~/.duck-keys/team.dev.pub is absent; your own copy still wins.
Assisted-by: Claude:claude-opus-5[1m]
* provision-board: read the dev key from the repo only
The ~/.duck-keys lookup was the primary path and the committed copy a
fallback, which is backwards now the key ships with the repo: the two
files are identical, so the home-directory branch only ever selected the
same bytes by a longer route. One default, and --dev-key for a key from
somewhere else.
Also repoints the doc paths in markdown prose that the earlier sweep
missed — it only covered .rs, .sh, .yml and .toml.
Assisted-by: Claude:claude-opus-5[1m]
* docs: repoint install-path-gap references that arrived with main
xtask/tests/artifact.rs and board-test.sh landed on main while this
branch was moving docs into groups, so they cite the old flat path.
Assisted-by: Claude:claude-opus-5[1m]
3 lines
114 B
Plaintext
3 lines
114 B
Plaintext
untrusted comment: minisign public key: F7C430D0F54E35CB
|
|
RWTLNU710DDE9wMtLX1x6kiSJZq5HwV8P2CKCagAvX6oONht787k/zvs
|