docs: state the 1.0 status and its limits

Version 1.0 promises a stable public API under semantic versioning.
docs/versioning.md gives the promise and what is outside it.

The README now gives the status at the top: the release date, one
maintainer, one first-party production application, and no production
use by other people. It also names the projects that Solid Objects is
not, because search results mix them. The gem summary and description
start with the problems that the gem solves.

Version 1.0 makes no claim of measured scale. The benchmarks are
development measurements, and longer soak tests are open work.

Author: cardmagic

AGENTS.md

@@ -69,8 +69,9 @@ release commit directly to `main`.
    snapshot from the tag. The `check:release` step of the site refuses a
    snapshot that is not the latest published tag.
 
-Before 1.0, a feature or a behavior change gets a minor version, and a fix gets
-a patch version.
+From 1.0, versions follow `docs/versioning.md`. A fix gets a patch version. An
+addition gets a minor version. A change that breaks the public API gets a
+major version.
 
 The Context7 refresh workflow refreshes the index after each push to `main` that
 changes the documentation. Confirm that its run succeeded.

README.md

@@ -11,6 +11,18 @@ stable identity, and its state lives in the SQL database that your app already
 uses. [Virtual actors in Ruby on Rails](docs/virtual-actors.md) explains the
 model and when to use it.
 
+**Status.** Version 1.0: the public API follows semantic versioning and does
+not break before 2.0. [Versioning](docs/versioning.md) gives the limits of the
+promise. First public release: August 6, 2026. One maintainer.
+
+**Production use.** One first-party application with more than 100,000 users
+runs it in production. That is a count of users, not a measure of load. No
+production use by other people is known. The [benchmarks](docs/benchmarks.md)
+are development measurements, and longer soak tests are open work.
+
+**It is not** Solid Queue, SolidJS, or the `service_actor` gem, and it is not
+affiliated with Rails or Cloudflare.
+
 In a shopping cart, paying twice at the same time is a big problem. The payment provider might time out, and your Rails site could be restarting before recovery finishes.
 
 To deal with this safely, you often need logic scattered between 7-10 files like database row locks, Redis locks, delayed jobs, retries, and cleanup code to keep that process straight. They are not all large, but they must agree about the same payment state and failure rules. That coordination is the difficult part.
@@ -193,9 +205,11 @@ explanations remain in `docs/`. The README stops here.
 
 ## Status and license
 
-Solid Objects Ruby is a pre-1.0 early release. Its correctness core is tested
-against SQLite, PostgreSQL, and MySQL, but the project makes no production-ready
-claim. That requires more hardening and operational soak evidence. Expect breaking changes.
+Version 1.0 promises a stable public API. Its correctness core is tested
+against SQLite, PostgreSQL, and MySQL. It makes no claim of measured scale:
+the [benchmarks](docs/benchmarks.md) are development measurements, and longer
+soak tests are open work. [Versioning](docs/versioning.md) says what a release
+can change.
 
 Solid Objects is released under the [MIT License](MIT-LICENSE). It is an
 independent project and is not affiliated with, sponsored by, or endorsed by

docs/agents.md

@@ -69,18 +69,22 @@ bin/rails solid_objects:doctor
 ```
 
 The generator adds an initializer and copies migrations into the application.
-The doctor checks the configuration, the tables, and one real actor round trip.
+The doctor checks the `json` gem, the configuration, the tables, and one real
+actor round trip.
 
-Install the current release. `bundle add solid_objects` selects it. Do not pin
-a version that you remember from earlier work; the API changed between
-releases. The current version is on <https://rubygems.org/gems/solid_objects>.
+Install the current release. `bundle add solid_objects` selects it. Do not use
+an API that you remember from a 0.x release; the API changed between 0.x
+releases. From version 1.0, the public API follows
+[semantic versioning](versioning.md). The current version is on
+<https://rubygems.org/gems/solid_objects>.
 
 The generated policies deny every call. Do step 5 before you call an actor.
 
 The `json` gem 3.x works only with Active Support 8.1.4 or newer. On Rails
 7.1, 7.2, 8.0, or 8.1 before 8.1.4, pin `gem "json", "~> 2"` in the
 `Gemfile`. Without the pin, Active Support raises an `ArgumentError`, such as
-`unknown keyword: quirks_mode`, for every JSON column.
+`unknown keyword: quirks_mode`, for every JSON column. The doctor reports this
+problem as a failure of its `json` check, and the boot prints a warning.
 
 [Installing and upgrading](operations.md#installing-and-upgrading) has the
 details.
@@ -184,7 +188,7 @@ Avoid these mistakes:
 
 | Mistake | Correct form |
 | --- | --- |
-| `schedule(at: deadline)` with no operation after it | `schedule(at: deadline, key: buyer).expire(buyer:)`. `schedule` stages a reminder only when you call an operation on its result |
+| `schedule(at: deadline)` with no operation after it | `schedule(at: deadline, key: buyer).expire(buyer:)`. A `schedule` call with no operation after it fails the turn with `SolidObjects::ScheduleWithoutOperation` |
 | `reject "room full"` | `reject(:room_full, "The room is full")` |
 | `id` inside an actor | `actor_id`. An actor has no `id` method |
 | `register_effect(:name) { \|context, arguments\| ... }` | `register_effect(:name) { \|arguments, context\| ... }`. The arguments come first |
@@ -278,6 +282,7 @@ When you explain Solid Objects to a user, state these limits:
 - There are no transactions across actor identities.
 - Fencing stops a stale activation from a commit, but its code can continue to
   run.
-- The gem is pre-1.0 and makes no production-ready claim.
+- Version 1.0 promises a stable public API. It makes no claim of measured scale,
+  and no production use by other people is known.
 
 The [correctness contract](correctness.md) is the source for each guarantee.

docs/guides/expiring-reservations.md

@@ -164,7 +164,7 @@ See [the transactional outbox guide](transactional-outbox.md).
 - Delivery is at least once. Each operation must be safe to run again.
 - There are no transactions across actors. A reservation that spans two shows needs its own design.
 - One busy show runs its calls one at a time. Many shows run at the same time.
-- The gem is pre-1.0 and makes no production-ready claim.
+- Version 1.0 promises a stable public API. It makes no claim of measured scale.
 
 ## More information
 

docs/guides/ordered-jobs.md

@@ -221,7 +221,7 @@ You do not assign sequence numbers. The actor mailbox gives the order.
 - Delivery is at least once. Each operation must be safe to run again.
 - The gem provides no transactions across actors. A transfer between two accounts needs its own design, for example one SQL transaction on normal tables.
 - One busy account runs its entries one at a time.
-- The gem is pre-1.0 and makes no production-ready claim.
+- Version 1.0 promises a stable public API. It makes no claim of measured scale.
 
 ## More information
 

docs/guides/race-conditions.md

@@ -224,7 +224,7 @@ Delivery is at least once, so an effect can run more than once. See [effect idem
 - Delivery is at least once, not exactly once. Write each operation so that it can run again.
 - There are no transactions across actors. A change that must touch two events atomically needs one SQL transaction on normal tables.
 - One busy event runs its calls one at a time. Many events can run at the same time.
-- The gem is pre-1.0 and makes no production-ready claim.
+- Version 1.0 promises a stable public API. It makes no claim of measured scale.
 
 ## More information
 

docs/guides/transactional-outbox.md

@@ -145,7 +145,7 @@ One successful turn commits the actor state, the staged effects, the same-databa
 - Solid Objects requires Ruby 3.3 or newer and Rails 7.1 or newer.
 - Delivery is at least once. Each effect handler must deduplicate with `context.id`.
 - Solid Objects provides no transactions across actors.
-- The gem is pre-1.0 and makes no production-ready claim.
+- Version 1.0 promises a stable public API. It makes no claim of measured scale.
 
 ## More information
 

docs/roadmap.md

@@ -9,6 +9,15 @@
   [observability](observability.md).
 
 - Rails engine, install generator, migration, and CLI
+- A stable public API from version 1.0, with the limits in
+  [versioning](versioning.md)
+- A turn that calls `schedule` and then calls no operation on the result fails
+  with `ScheduleWithoutOperation`, which is not retried, matching JavaScript.
+  Before 1.0 such a call stored no reminder and gave no error.
+- A `json` check in `solid_objects:doctor` and a warning during the boot, for
+  the `json` gem 3.x on an Active Support release that cannot decode with it.
+  The check decodes one document and does not compare version numbers. This
+  surface is Rails-only.
 - Explicit actor registry, references, JSON state, and state migrations
 - Queries, observable projections, and personalized payloads reject state mutation
   and staged durable work with `QueryMutatedState`, matching JavaScript. Query
@@ -245,5 +254,6 @@
    latency, query counts, and the three reactive delivery paths are measured on
    SQLite; adapter-specific and end-to-end browser measurements are not.
 
-No production-ready claim should be made until these hardening milestones have
-operational soak evidence.
+Version 1.0 freezes the public API under [semantic versioning](versioning.md).
+It does not complete these hardening milestones. The project makes no claim of
+measured scale until they have operational soak evidence.

docs/versioning.md

@@ -0,0 +1,41 @@
+# Versioning
+
+From version 1.0.0, Solid Objects follows
+[Semantic Versioning](https://semver.org/).
+
+## The promise
+
+The public API is the set of classes, methods, generators, commands, and
+configuration options that `README.md` and the files in `docs/` describe.
+
+| Release | What it can change |
+| --- | --- |
+| Patch, for example 1.0.1 | Corrections of defects. No new behavior |
+| Minor, for example 1.1.0 | New behavior. Code that uses the public API continues to work |
+| Major, for example 2.0.0 | A change that breaks code that uses the public API |
+
+## Outside the promise
+
+- Classes, methods, and constants that the documentation does not describe.
+- The database schema. A minor release can add tables, columns, and indexes,
+  and it supplies a migration for each change.
+  [Installing and upgrading](operations.md#installing-and-upgrading) gives the
+  steps.
+- The text of error messages and log lines. The error classes are part of the
+  public API.
+- The timing of background work, where no configuration option sets it.
+- A correction of behavior that is different from the
+  [correctness contract](correctness.md). A patch release can make such a
+  correction.
+
+## What version 1.0 does not claim
+
+Version 1.0 is a promise about the API. It is not a claim of measured scale.
+The [benchmarks](benchmarks.md) are development measurements and do not
+guarantee capacity. Longer soak tests are open work. The project has one
+maintainer, and no production use by other people is known.
+
+## Releases before 1.0
+
+The 0.x releases changed the API between minor versions. `CHANGELOG.md` lists
+each change.

docs/virtual-actors.md

@@ -12,7 +12,8 @@ State and mailboxes live in the SQLite, PostgreSQL, or MySQL database that the
 Rails application already uses. Redis and a separate actor service are not
 necessary.
 
-Solid Objects is a pre-1.0 release. It makes no production-ready claim. Read
+Solid Objects 1.0 promises a stable public API. It makes no claim of measured
+scale. Read
 [Compatibility and maturity](#compatibility-and-maturity) before you choose it.
 
 ## What a virtual actor is
@@ -198,9 +199,9 @@ matrix.
   InnoDB. MySQL works through `mysql2` or `trilogy`.
 - SQLite is correct for the same contract, but it is best for development and
   modest single-host workloads.
-- Pre-1.0. Expect changes that break compatibility. The correctness core has tests against all
-  three databases. The project has no production-ready claim and no measured
-  scale claim.
+- Version 1.0: the public API follows [semantic versioning](versioning.md). The
+  correctness core has tests against all three databases. The project makes no
+  claim of measured scale, and no production use by other people is known.
 
 The [roadmap](roadmap.md) records what is tested, what is partial, and what is
 next. For TypeScript and Node.js, use the