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.

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

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

“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

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:

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:

{
  "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

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: 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: includes conditions for retaining notices in source and binary distributions. The generator uses pronunciation data to filter words.
• BIP-39 specification and reference implementation licence: identify MIT licensing; the original imported revision still needs a provenance record.
• google-10000-english licence: 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.

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. For the product overview, return to The Rotational Word.