# The Rotational Word ## Product and integration guide **Edition 1.0 · 2026-09-16T22:15:00-04:00** **Status: in development.** This guide describes the existing TAGII implementation, called **Word Key**, and the direction for a standalone product. It is not an announcement that standalone registration, installation or third-party integration is available. [TOC] ## 1. Why it exists Authentication is usually a moment we complete and forget. The Rotational Word asks whether that same moment can give something back: a word we recognise, a meaning we discover, or a spelling that becomes familiar through use. The idea is to show changing words with their meanings where a person would otherwise read a numerical code. Reading and typing a word can make its spelling part of that small moment. Learning fits into something they already need to do. This is the product's purpose, not a measured promise about learning outcomes. The existing implementation uses three words together. **The Rotational Word** is the working product title; **TAGII Word Key** is the name in the app and source code. A final standalone name has not been settled. A personal collection of encountered words and integration into other products are planned directions. Neither is a finished feature documented here. ## 2. What exists today | Area | Current source state | What still needs proof or work | | --- | --- | --- | | Word generation | Go engine and Flutter implementation; default three-word phrase, changing every 60 seconds | Complete device and service release verification | | App experience | Setup screen, tappable words, countdown and definition sheet | End-to-end setup and verification on supported physical devices | | Server integration | Enrollment, phrase verification and definition handlers | Complete handler, database, replay and lockout execution evidence | | Learning | Handwritten meanings plus a larger generated definition collection | Full active-list coverage, editorial review and licence reconciliation | | Word lists | Existing app and enrollment use `general-v1`; a larger `general-v2` exists in source | Coordinated app/server integration before v2 enrollment can be offered | | Recovery | Re-enrollment code exists and replaces the account's active Word Key seed | Approved recovery policy and lost-device proof | | Standalone product | Product purpose and existing platform implementation | Packaging, release terms, integration onboarding and distribution | This guide's review includes source inspection and isolated tests. Earlier installation records report a running backend, but that is different from proving the entire user journey. An available endpoint or a displayed phrase alone is not proof of successful authentication. ## 3. The app experience ### Set up In the current app source, Word Key is reachable from Settings and Security Setup. If this device has no stored Word Key seed, the screen offers **Set up Word Key**. Setup requires an authenticated TAGII session and a secure server connection. The server creates a random seed and returns it during enrollment. The app stores it with the platform's secure-storage service, together with the phrase parameters. A seed is the secret used to generate future phrases. It is not a word, password or definition. Do not put it in messages, screenshots, analytics or support requests. The server also retains an encrypted copy for verification, so this is a shared-secret design, not a device-only private-key design. ### Read the words After setup, the app calculates the current phrase on the device. The countdown shows when the displayed phrase will change. The screen refreshes the phrase at the boundary and when the app resumes. The default is three words every minute. The server's verification policy allows neighbouring time windows to accommodate clock differences. A countdown reaching zero means the display changes; it is not a promise that every service will reject that phrase at the exact same instant. ### Explore a meaning Tap a word to open its definition sheet. The current app fetches definitions from TAGII's server and keeps fetched results during that screen's lifetime. There is no demonstrated persistent vocabulary notebook or offline definition library in this flow. A missing meaning does not change the generated phrase. The app can show that a definition is unavailable while the words remain visible. ### Complete a requested check Use the phrase only within an authenticated flow you intended to complete. The screen's optional **Continue** button returns control to its caller. It does not itself send the phrase to the server or establish that the requested check succeeded. Integration code must obtain and enforce the actual verification result. ## 4. What works offline | Action | Network needed? | | --- | --- | | Generate a phrase after successful setup | No; uses the stored seed, clock and bundled list | | Set up or replace a Word Key | Yes | | Fetch a meaning in the current app | Yes | | Verify through TAGII's server | Yes | | Use a separate on-device unlock flow | Depends on that flow's own checks; not equivalent to server verification | “Offline generation” must not be described as “all authentication works offline.” A phone can calculate words without reaching the server, while the service requesting access still needs to verify them. ## 5. How the pieces connect ```text Authenticated app | | secure enrollment v TAGII service creates the seed | | | encrypted server copy | setup response v v Account record Device secure storage | | | | seed + clock + versioned word list | v | Changing word phrase | | +----- verification ------+ Tap a word -> authenticated definition request -> meaning or unavailable ``` The generator uses HMAC-SHA256 with an eight-byte time counter. It selects words from fixed two-byte fields of the digest. It follows the time-based shared-secret model, but the word encoding is TAGII-specific. Ordinary six-digit authenticator applications are not drop-in compatible with this output. The pure generator does not maintain attempt counts or consume accepted phrases. The calling service owns replay prevention, attempt limits, lockout and access decisions. An integration must not treat a local calculation as permission to enter another service. ## 6. Integration reference **These are source-derived contracts for the existing TAGII handlers, not a released third-party API or a live setup tutorial.** No enrollment is performed by this document. Development integrations need an approved test environment, supported account lifecycle and release agreement. The paths below are complete paths from the service origin. If your configured API base already ends in `/api/v1`, append only `/wordkey/enroll`, `/wordkey/verify` or `/wordkey/define`. Requests require the authenticated session's bearer token. Keep tokens, seeds and submitted phrases out of logs. Examples describe field names without real credentials. ### Enrollment **`POST /api/v1/wordkey/enroll`** The current handler consumes no request-body configuration. Sending a word-list version does not select another list. Success is **201 Created**, with these fields: | Field | Meaning | | --- | --- | | `status` | `ok` | | `seed_hex` | Secret seed encoded as 64 hexadecimal characters; sensitive enrollment response | | `wordlist_version` | `general-v1` | | `word_count` | `3` | | `step_seconds` | `60` | | `message` | Human-readable setup result | Enrollment changes account state. Repeating it creates a new seed and replaces the previous active one. Do not automatically retry it as if it were a read-only request, or use it merely to repair a failed definition lookup. The old device's stored seed will not match the replacement. ### Phrase verification **`POST /api/v1/wordkey/verify`** The JSON request field is **`phrase`**, containing the ordered words separated by spaces. It is not `words`. The verifier normalises letter case and whitespace. Success is **200 OK**, with `status: "ok"` and `message: "Verified."`. The current handler records the accepted time counter. A repeated valid phrase returns **409 Conflict**, and the caller should wait for the next phrase rather than treat that response as a new success. Incorrect phrases return **401**. The fifth consecutive counted failure enters a 15-minute lockout and returns **429**. The request path can also return 401 or 429 for other reasons; handle the returned error and the authenticated session state rather than interpreting a status number alone. ### Definitions **`GET /api/v1/wordkey/define?words=anchor,meadow`** The parameter is **`words`**, a comma-separated list. It is not a singular `word` parameter or a path segment. The handler considers the first eight comma-separated positions, trims and lowercases them, skips blanks and returns: ```json { "status": "ok", "definitions": { "anchor": "a heavy object that holds a boat in place in the water.", "meadow": "a field of grass and wildflowers." } } ``` These are existing handwritten definitions from the source. An unknown word has an empty string as its value. The endpoint requires authentication and identity resolution; it is not an anonymous public dictionary service. ### Responses and recovery | Status | Meaning in this interface | Appropriate caller response | | --- | --- | --- | | 200 | Verification or definition request succeeded | Inspect the response for that operation | | 201 | Enrollment succeeded | Store the setup result securely; do not log it | | 400 | Invalid verification input or empty definition query | Correct the request; do not repeat unchanged | | 401 | Invalid session or incorrect phrase | Distinguish session recovery from a failed phrase | | 404 | No active Word Key for verification | Offer the approved setup/recovery path | | 409 | Valid phrase already used | Wait for a new phrase | | 429 | Lockout or request limit | Respect the service's wait condition; do not retry rapidly | | 500 | Processing, identity or storage failure | Report failure and preserve the user's current setup | | 503 | Required service/configuration unavailable | Stop the attempted check; do not grant access | Handler errors use `status: "error"` and an `error` message. Routing and middleware may produce additional responses. A service integration must test its complete authenticated request path. The separate `gate/wordkey` route belongs to TAGII's existing web-gate integration. It is not a general-purpose replacement for these handlers or a documented standalone integration entry point in this edition. ## 7. Troubleshooting and device changes **“Not set up on this device.”** The app found no local seed. This does not prove whether the account has an enrollment on another device. Follow setup or account recovery deliberately. **“Could not open a secure connection.”** The app did not establish its required secure client. Check connectivity and the approved app/service configuration. Do not bypass the connection check to receive a seed. **Words visible, meaning unavailable.** Generation and definition lookup are separate. Check connectivity and session state; a missing meaning alone does not require re-enrollment. **Phrase rejected near a change.** Use the current phrase and keep the device clock correct. If the phrase was already accepted, wait for the next one. Avoid repeated guesses. **Locked after repeated attempts.** Wait for the lockout to end. Re-enrollment is also refused while the current enrollment is locked. **Lost or replaced device.** The implementation has a re-enrollment path under main-account authentication. Its release policy and physical lost-device journey remain to be completed. This guide does not promise a finished recovery service. **Clearing local Word Key storage.** The source's `clear()` function removes local data only. It does not revoke the server-side enrollment. A production management interface must make that distinction clear. ## 8. Word lists, meanings and permissions The app and enrollment handler currently use the 4,096-word `general-v1` list. Source also contains an 8,192-word `general-v2` list and matching generated definitions, but the current enrollment registry and Flutter generator do not offer that version together. The definition resolver tries the original handwritten meanings first, then the newer generated collection. Old statements that the service has only 20 possible definitions are therefore outdated. This does not establish that every word in the active v1 list has a meaning. The recorded v1 inputs are BIP-39 and `google-10000-english`. The recorded v2 inputs are WordNet and CMUdict. Their names identify source material, not a partnership. Words must also be readable, typeable and distinguishable when spoken. Similar-sounding words and unfamiliar spellings need usability testing. Dictionary selection, notices, reproducible generation and commercial distribution need to be reconciled before a standalone release. The primary source notices checked for this edition are: - [Princeton WordNet licence](https://wordnet.princeton.edu/license-and-commercial-use): permits use and redistribution under its notice and disclaimer conditions. The page displays the 3.0 licence; the exact notice from the historical 3.1 input archive still needs to be recorded. - [CMUdict licence](https://raw.githubusercontent.com/cmusphinx/cmudict/master/LICENSE): includes conditions for retaining notices in source and binary distributions. The generator uses pronunciation data to filter words. - [BIP-39 specification](https://raw.githubusercontent.com/bitcoin/bips/master/bip-0039.mediawiki) and [reference implementation licence](https://raw.githubusercontent.com/trezor/python-mnemonic/master/LICENSE): identify MIT licensing; the original imported revision still needs a provenance record. - [google-10000-english licence](https://raw.githubusercontent.com/first20hours/google-10000-english/master/LICENSE.md): describes educational, personal and research use and points commercial users toward LDC licensing. The legacy combined list must not be labelled commercially cleared without resolving this. These findings identify release work, not a legal clearance. The generated data has not been independently reproduced from pinned original input archives. No Webster's, Merriam-Webster or Oxford partnership is established by the reviewed material. The guide does not grant a licence to redistribute the word lists or definitions. The underlying source notices and terms must govern each distributed artifact. ## 9. Testing and release status The documentation review executed the existing Go engine suite and selected handler/guard tests, plus relevant Flutter tests. Positive cases include deterministic matching phrases and seed sealing. Refusal cases include incorrect or expired phrases, invalid input configuration and tampered encrypted seed data. Some tests inspect source text; they are useful regression checks but do not execute the corresponding handler or prove a live database transaction. Tests that use mocked storage do not prove physical-device secure storage. The release checklist remains open for: - Complete setup, verification, replay refusal and lockout through the real handler/database path with production-equivalent permissions. - Physical-device setup, restart, clock changes, app upgrade and lost-device recovery. - Consistent app/server word-list version handling and migration. - Word-list permissions, notices, reproducibility, accessibility and definition quality. - Verified enrollment lifecycle and management behaviour. - Confirmed cross-device access flow and independent security review. - Standalone distribution, installation instructions and a supported integration contract. Authentication design is security-sensitive. The words do not themselves establish phishing resistance, identity certainty or protection on a compromised device. No certification or security-superiority claim is made here. ## 10. Source map and documentation ownership This guide is maintained in TAGIIv4 at `docs/reference/2026-09-16-rotational-word-guide.md`. Website HTML and Markdown downloads are generated from that source. The website is not a separate editable product specification. | Source in TAGIIv4 | What it contributes | | --- | --- | | `docs/doctrine/2026-08-30-rotational-word.md` | Product purpose and standalone direction | | `docs/phases/WB4-PH10.00-word-key.md` | Original plan, current reconciliation, implementation map and open engineering work | | `docs/workbooks/current/WB-PH10.00-word-key-INSTALLATION-I01.md` | Dated installation observations and incomplete release gates; historical text is preserved | | `go/internal/wordkey/` | Word generation, seed encryption, word lists, definitions and tests | | `go/cmd/access-code-api/wordkey_handlers.go` | Actual enrollment, verification and definition contracts | | `flutter/lib/services/wordkey_service.dart` | Local generation, secure storage and network calls | | `flutter/lib/screens/auth/word_key_screen.dart` | Setup, countdown and definition interface | The later passkey/vault exploration is explicitly on hold and does not replace the approved product direction. Original workbooks remain unchanged; current corrections belong in the phase record. This edition documents the current implementation and known gaps. It does not turn an unfinished feature into a completed one. ## 11. Questions and further work For product or integration discussion, [contact TAGII](https://tagii.com/contact). For the product overview, return to [The Rotational Word](https://tagii.com/rotational-word).