docs: explain adoption costs, alpha limits and human evidence

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+- Document adoption decisions for existing ObjectId/search workflows, additional
+  alias and mapping costs, alpha versus wire compatibility, stable-release gates
+  and a human-entry study protocol. Runtime, formats and published packages are
+  unchanged; no human-entry advantage is claimed.
+
 ## 0.1.0-alpha.3 — 2026-10-28
 
 Workflow examples and documentation; runtime JavaScript, public APIs and the

README.md

@@ -22,6 +22,26 @@ The image is generated from [recorded evidence](docs/evidence.json). See [measur
 
 ## Try it
 
+**Already have an ObjectId, invoice number or working search? Keep it unless an
+observed manual-entry problem justifies another representation.** RefMint does
+not make database lookup faster or authorize access. The built-in existing-ID
+codecs support uint64 and UUID, **not MongoDB ObjectId**. A separate random alias
+for ObjectId needs a stored field or mapping, a unique index, collision handling,
+backfill and lifecycle maintenance. The uint64/UUID codecs can avoid that mapping,
+but still add UI, dependency and compatibility work.
+[Adoption decision and costs](docs/adoption.md).
+
+**No human-entry advantage is established.** Selected typo mutations and codec
+timings cannot show that people are faster or make fewer errors. Compare the
+existing workflow, a simple alias and RefMint with real participants before making
+that claim; retain failures and report manual entry separately from copy/paste.
+[Measurement protocol](docs/manual-entry-study.md).
+
+The package remains alpha. Frozen v1 wire encoding is narrower than stable APIs,
+support or application readiness. [Criteria for a stable release](docs/stability.md)
+are separate from the decision to adopt: a stable release alone would not create
+a need for integration.
+
 **Would an extra reference help?** Try the
 [PDF/phone lookup experiment](docs/workflows.md): existing number or hostname,
 five-character alias, and RefMint on the same records. The sample fleet code is

docs/adoption.md

@@ -0,0 +1,48 @@
+# Decide whether another reference is useful
+
+Start from a support task that is currently difficult, not from a preferred ID
+library. If users already paste a link or find the right record using ObjectId,
+an invoice number, a name or a hostname, keeping that workflow may be best.
+RefMint's checksum can reject some mistyped public references before lookup; it
+does not speed up a database query, identify a customer or grant access.
+
+| Existing workflow | First choice | What RefMint would add |
+| --- | --- | --- |
+| ObjectId with working search or copied links | Keep ObjectId and the current search | No built-in ObjectId codec; a new alias requires a field/mapping or a separately specified codec |
+| A short ticket or invoice number people already use reliably | Keep the number | A longer checked representation, new terminology and training |
+| Repeated manual entry of uint64 or UUID values with measured mistakes | Compare current input, a simple alias and RefMint | Reversible checked presentation of the same ID; no additional alias column required |
+| Copy/paste or QR scanning | Improve that path first | Checksum validation may still detect some corruption, but faster human entry is unproven |
+| Secret invitation or authenticated lookup | Use the application's security design | Nothing: a public reversible checksum is not a credential |
+
+Do not truncate an ObjectId to uint64, pretend it is a UUID, or silently convert
+an unsupported identifier. Such changes lose information or create an undocumented
+format. A new codec should follow a demonstrated need and an explicit compatibility
+contract. BookCars and Movinin feedback showed no established need beyond their
+existing ObjectId workflow; a later stable RefMint release would not invalidate
+that decision or constitute permission to resume an integration.
+
+## Account for the integration cost
+
+For a random alias stored alongside an existing key, budget for the new field or
+mapping table, unique index, collision retries, backfill, deletion/retention rules,
+backup/restore and tenant boundaries. Decide whether aliases can ever be reused.
+Both a simple alias and a RefMint random reference have these lifecycle costs.
+
+For the existing uint64/UUID codec, decoding returns the original key, so a mapping
+can be avoided. You still own namespace/version selection, input validation,
+presentation, error messages, old-reader retention, tests, dependency upgrades and
+support documentation. Keep existing URLs, regulated numbers and search available.
+Do not store display grouping as a different key from canonical storage.
+
+All routes must apply the same server-side tenant and permission checks. RefMint
+does not prove record existence or prevent a valid reference from selecting the
+wrong record. Ask users to confirm record context before sensitive operations.
+
+## Decide on evidence
+
+Define the actual problem and acceptable costs before testing. Use
+[the manual-entry protocol](manual-entry-study.md) and retain a no-adoption outcome.
+A checksum test demonstrates an algorithmic property; it does not demonstrate
+less support work, fewer human errors, faster entry or a product's need for RefMint.
+No such human-entry advantage is currently established. An opt-in pilot is an
+evaluation, not proof of adoption or readiness for all users.

docs/manual-entry-study.md

@@ -0,0 +1,49 @@
+# Measure manual-entry value before claiming it
+
+**Status: no human-entry benefit is established by this repository's evidence.**
+The current [workflow results](workflow-results.md) are synthetic selected cases.
+Codec throughput, mutation detection and automated browser actions are not human
+completion times or error rates. This protocol is a plan, not collected data.
+
+## Compare the actual task
+
+Use the same authorized record lookup and confirmation task for three routes:
+the current identifier/search workflow, a simple alias, and RefMint. Preserve
+existing identifiers and credentials. Use consented, non-sensitive records and
+representative ID lengths; do not choose only nearby numbers that favor one route.
+If the real workflow uses pasted links or QR codes, include it instead of assuming
+that users must type. Keep manual entry and copy/paste results separate.
+
+Predefine task order, practice, time limit, exclusion rules and the benefit/cost
+criteria with the product owner before collecting results. Use different records
+for each task and counterbalance route order across participants. State whether
+the task is visual transcription, phone dictation or a real support task; do not
+generalize one into another. A single-person synthetic pilot is exploratory only.
+
+## Record outcomes without losing failures
+
+Measure elapsed time from showing the task to the first query, first correct
+lookup and final correct-record confirmation. Record first-query success, rejected
+input, not-found, wrong-record lookup/confirmation, skipped tasks, timeouts and
+interruptions. Keep practice separate. Do not equate delete-key counts with typo
+counts: silent corrections before submission are only partly observed.
+
+Retain every started trial and all protocol violations. Report participant/task
+counts and completion rates next to time summaries. Report successful-trial median
+times with their denominators and spread; do not make failures disappear from the
+comparison or turn an aborted timer into a successful time. Separate search errors
+from interruptions and unauthorized records. Avoid retaining entered private IDs
+or raw keystrokes; use anonymous task identifiers and the minimum necessary data.
+
+## Interpret conservatively
+
+Compare paired routes within the same task conditions. Explain sample size, order
+effects, participant experience, record length and any exclusions. Retain raw
+consented observations privately and publish only approved aggregates and methods.
+A small pilot can identify usability problems and guide a larger study; it cannot
+establish a population-wide advantage or prove need in another application.
+
+If the current ID or simple alias is faster, easier or sufficient, report that and
+keep it. RefMint's own stability and its [integration costs](adoption.md) remain
+separate questions. Do not publish invented human timings or label automated QA
+as participant observations.

docs/stability.md

@@ -0,0 +1,38 @@
+# Alpha scope and stability criteria
+
+RefMint 0.1.0-alpha.3 is a prerelease. npm publication and successful CI do not
+change that status. Pin the exact reviewed version for an evaluation and keep the
+existing identifier/search path available. There is no stable-release date promised.
+
+The [existing-ID v1 wire contract](format-v1.md) freezes its layout, canonical
+encoding and accepted presentation forms. Incompatible wire changes require a new
+version and reader. This is not a promise that the alpha API, error diagnostics,
+supported environments or support policy will never change. Applications must
+retain the readers needed for references they have already issued.
+
+## Criteria before a stable release
+
+- Review and freeze the public API and error behavior; document any migration from
+  alpha with examples, including rejected input and exact integer handling.
+- Verify released-format compatibility against the retained frozen vectors and an
+  independent implementation; never update old vectors to conceal incompatibility.
+- Verify the exact package archive in supported Node/browser environments, including
+  TypeScript consumers, and record its source identity and checksums.
+- Resolve known correctness/security blockers and document remaining limits,
+  versioning, deprecation and maintenance policies.
+- Review consumer feedback and document concrete supported uses, integration cost
+  and an exit/migration path. Any claim of faster entry or fewer human mistakes
+  additionally requires human evidence with its method and limitations published.
+
+These are gates to review, not a statement that all are already met. The current
+synthetic tests and release records cover only their named properties and versions.
+A stable API could be useful without a speed advantage; conversely, a faster
+single-person trial would not establish API stability.
+
+## Stability is not an adoption requirement by itself
+
+A stable release can remove a prerelease-policy obstacle. It cannot create a
+manual-entry problem where existing IDs and search already work. Adoption remains
+a separate product decision, including the dependency and operational costs in
+[the decision guide](adoption.md). Do not reopen declined integrations just because
+the version label changes.

docs/when-not-to-use.md

@@ -2,6 +2,10 @@
 
 Start with the identifier and search workflow users already know.
 
+See the [adoption and cost guide](adoption.md), [stability criteria](stability.md)
+and [human comparison protocol](manual-entry-study.md). ObjectId has no built-in
+RefMint codec; working ObjectId search does not by itself call for a new alias.
+
 | Situation | Prefer |
 | --- | --- |
 | Existing invoice/quote numbers or hostnames are short and lookup works | Keep them; a second identifier creates training and maintenance cost |