From 13111d73a5214eabc4ca232bf280b864c5abadac Mon Sep 17 00:00:00 2001 From: Brian Miller Date: Sat, 22 Aug 2026 21:16:39 +0000 Subject: [PATCH] docs: install from the release, and start a changelog Two consequences of having a first release. The quickstart still opened with `go build -o stone`, so the six prebuilt archives now attached to v0.1.0 were invisible and every user compiled their own; it now downloads one and mentions the full target list, keeping the build-it-yourself line as the alternative it now is. And there was no changelog, so "what changed since v0.1.0" had no answer beyond commit subjects. Seeded with the state at first tag, in the same format the platform repo uses, including the two caveats a reader needs: the field list is hand-maintained and can lag a platform release, and `auth login` is interactive on purpose. Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 10 ++++++-- 2 files changed, 72 insertions(+), 2 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..5b0dad2 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,64 @@ +# Changelog + +All notable changes to this project are documented here. The format follows +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow +[Semantic Versioning](https://semver.org/spec/v2.0.0.html) — with the pre-1.0 +caveat that a minor version may break something. Pin what you deploy. + +History before `0.1.0` is not reconstructed here; `git log` is the record for +that period, and this file starts where the versioned releases do. + +## [Unreleased] + +_Nothing yet._ + +## [0.1.0] - 2026-08-22 + +First tagged release, and the first one you do not have to compile yourself. +The CLI has been in use against the platform for months; this tag marks the +point at which it is packaged for other people to run. + +### Added + +Summarising the state at first tag rather than the path to it: + +- **Contexts.** Named bundles of server URL, auth token, current organization, + optional NATS context and optional workspace path, under + `$XDG_CONFIG_HOME/stone/`, with `0600` on anything secret-bearing. One binary + points at `local`, `staging` and `prod` without re-typing connection details. +- **Auth and organizations.** `auth login` / `whoami` / `logout`, and + `org switch`, which updates `users.current_organization` **on the server** so + the console and the CLI agree on context. +- **Typed CRUD over the platform's collections.** Things, locations, both type + collections, the thing-type contract graph, message schemas, memberships, + invites, the `nats_*` and `nebula_*` collections, and leaf nodes — generated + from one declarative table, so every entity behaves the same way and the name + aliases are forgiving. Lookup by 15-char id or by natural key (`code`, `name`, + `hostname`). +- **Declarative workspaces.** `pull` writes one YAML file per record; + `apply` reconciles them back through PocketBase's transactional `/api/batch`. + Idempotent, and it never deletes — a one-way additive upsert, not a + convergence loop. +- **NATS, JetStream and KV.** `nats pub/sub/req`, `kv` get/put/del/ls/watch plus + bucket lifecycle, and `js stream` management, reusing your existing `nats` CLI + contexts so JetStream domains are honoured. +- **Per-organization NATS credentials.** Credentials are per-membership on this + platform, so `org switch` re-issues the local `.creds` and a matching + `nats` CLI context. `nats creds rotate` rotates your own through the + platform's dedicated route, which every role may call. +- **Scripting discipline.** `-o table|json|yaml`, structured output on stdout and + human messages plus generated passwords on stderr, so + `stone thing create … --random-password -o json | jq .id` does the right thing. +- **`SKILLS.md` and a Claude Code skill**, describing the same command surface + for humans and for an assistant driving the CLI. + +### Notes + +- **The field list is hand-maintained**, not derived from the platform's + `schema.json`, so a given release can lag a platform release. If a field + exists in the console but has no flag here, that is why — see `cmd/entity.go`. +- `auth login` is interactive by design; credentials cannot be discovered by the + CLI, which is also what stops an assistant authenticating as you. + +[Unreleased]: https://github.com/stone-age-io/stone-cli/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/stone-age-io/stone-cli/releases/tag/v0.1.0 diff --git a/README.md b/README.md index 5b503ed..78144cf 100644 --- a/README.md +++ b/README.md @@ -20,8 +20,14 @@ the Control Plane — that it talks to. ## Quickstart ```sh -# 1) Build -go build -o stone +# 1) Get the binary -- prebuilt, for the platform you are on +VERSION=0.1.0 +curl -sSLO https://github.com/stone-age-io/stone-cli/releases/download/v${VERSION}/stone_${VERSION}_linux_amd64.tar.gz +tar xzf stone_${VERSION}_linux_amd64.tar.gz # unpacks ./stone, LICENSE, README.md, SKILLS.md + +# linux, darwin and windows are all built, amd64 and arm64 each: +# https://github.com/stone-age-io/stone-cli/releases/latest +# Or build it yourself, which needs Go 1.25+: go build -o stone # 2) Create a context pointing at your platform server ./stone context create local \