reference/terminology.md
at 55a1b0bNerudo documentation terminology
The account guides in this repository use ASD-STE100 Issue 9 as their writing reference. The official source is ASD-STE100, Issue 9, 2025-01-15. This record does not claim certification or independent compliance approval.
The review used the dictionary and rules for technical terms, sentence structure, procedures, and descriptive text. Instructions use the command form, one action per sentence, and short sentences. Descriptions use the active voice and one topic per paragraph. Commands and quoted interface labels keep their exact product spelling. Prerequisites and command examples use expandable details so the forms remain easy to find.
Technical nouns
These terms have a fixed meaning in the account guides. Do not use different terms for the same item.
| Term | Meaning and boundary |
|---|---|
| Account | The Nerudo identity that owns the account settings. |
| Account ID | The stable account identifier. Organization membership checks this value with the username; names alone do not transfer membership to another account. |
| API | Application programming interface. In this guide, the named-repository HTTP API. |
| Armored file | A text representation of OpenPGP data. |
| Authorized tools | The account page at /settings/developer. It shows the signed-in user's developer credentials across repositories. The user can revoke them here. The page does not make credentials. |
| Bearer header | The HTTP Authorization header with the Bearer scheme and the developer credential. |
| Challenge | The exact downloaded file for one account, session, public key, purpose, and five-minute period. |
| CLI | Command-line interface. The Nerudo CLI can use the existing approval key. |
| Detached signature | A signature in a file separate from the signed data. |
| Developer credential | The secret value beginning with nrd_dev_ and 43 random URL-safe characters. Repository settings make a credential for one fixed repository. The credential uses the account of the user who made it. Credentials made earlier can retain multiple repository scopes. Do not use “API key,” “signing key,” or “password” as synonyms. |
| Developer access | The repository settings page that makes a personal developer credential for its fixed repository. The owner page with this name provides repository links only. |
| Ed25519 | A digital signature algorithm. Nerudo's raw Ed25519 approval key is separate from an OpenPGP certificate. |
| Environment variable | A named value supplied to a process. The example name NERUDO_TOKEN is not a real secret. |
| Expiration date | The time after which a developer credential or key is no longer valid for the applicable operation. |
| Fingerprint | A full public-key identifier. Use the full fingerprint, not a short key ID. |
| Git | The version-control program. |
| Git clone | The Git operation that obtains a repository copy. Developer credentials do not authorize this operation. |
| Git commit | A record of repository changes. |
| Git commit signing | The local Git operation that adds a digital signature to a new commit. Enrollment on Nerudo is not a prerequisite. Nerudo does not currently verify commit signatures. |
| Git push | The Git operation that sends repository updates. Developer credentials do not authorize this operation. |
| GPG | The GnuPG program. |
| GPG key | The public/private key material and its OpenPGP certificate as managed by GPG. The ownership check accepts a public certificate only. |
| HTTP request | A request that a program sends with the HTTP protocol. |
| JSON | A text data format. |
| Keyserver | A service that publishes OpenPGP public keys and revocations. Nerudo does not query keyservers for later revocations. |
| Landing | The Nerudo operation that adds an approved change to a repository. A developer credential does not authorize landing. |
| Management permission | Permission to change organization or repository metadata. A namespace owner or organization owner/admin can hold it. It does not replace private code access or approval policy. |
| Namespace | The owner part of an owner/repository address. Transfer requires management authority in the source and target namespaces. |
| Nerudo approval key | The existing raw Ed25519 public key in the account profile and its separately held private key. Repository policy grants its approval authority. GPG enrollment does not change this key or its authority. |
| OpenPGP | The standard format that GPG uses for keys and signatures. |
| Ownership verified | The interface status after a successful GPG challenge signature check. It does not verify an email address, a Git commit, or future key status. |
| Owner | The user or organization that owns a repository. The developer access overview at /OWNER/settings/developer links to repository settings. It does not issue shared organization credentials. |
| Organization role | An organization membership level: Owner, Admin, or Member. Owners change owner/admin assignments. A user can leave their own membership, except the final active owner. Repository policy roles are separate. |
| Operator setup | The explicit assignment of an initial owner for an organization without personal management records. Existing repository roles do not silently claim organization ownership. |
| Passphrase | A password that protects a private key. |
| Private key | Secret signing data. It remains on the user's computer or authenticator; the account help never instructs its upload. |
| Public key | The non-secret key data that a verifier uses for signature checks. |
| Public / Private | Repository visibility states. Public permits reading without sign-in. Private requires repository permission. Visibility does not grant approval authority. |
| Repository | The code and change history for an owner/repository name. Developer access at /OWNER/REPO/settings/developer fixes the new credential to this repository. Each API request requires current account permission. |
| Repository policy | The rules in nerudo.toml for membership, approval keys, roles, checks, and approval requirements. Organization settings do not edit or bypass this file. |
| Revocation | A change that stops future use of the affected credential in Nerudo. “Mark revoked” for a GPG record does not publish a GPG revocation. |
| Shell history | A shell's record of entered commands. Real credentials must not be entered as literal values in command examples. |
| Sign-in method | An OAuth provider or passkey that gives account access. A GPG ownership record is not a sign-in method. |
| Seal | The Nerudo approval signature bound to one commit and the applicable repository policy. The CLI asks for confirmation before it sends a seal. |
| Terminal | The application in which the user enters commands. |
| Trunk ID | The identifier that the Nerudo CLI uses for the repository's sequencer. The help uses a placeholder, never a real private identifier. |
| Transfer | A change to a repository's owner or name. The same repository history, visibility, policy membership, and approval keys remain. Transfer revokes all credentials for the source repository address, including credentials with multiple repositories. New credentials use the target address. |
| Agent delegation | Authority given to an agent to act for a user. A developer credential does not grant this authority. |
Technical verbs
The guide uses these verbs only for the specified computer processes. Rule 1.12 permits subject-specific verbs; these are not permission to replace approved general verbs.
| Verb | Computing meaning |
|---|---|
| Confirm | Complete the fresh sign-in process with a connected provider or passkey. |
| Copy / paste | Transfer unchanged text through the clipboard. |
| Download / upload | Transfer a file from or to Nerudo. |
| Enter | Supply text or a command to a field or terminal. |
| Expire | Reach the configured time at which a challenge or credential stops. |
| Install | Put the GPG program on a computer. |
| Revoke | Disable a credential or mark a GPG record revoked in Nerudo. |
| Save | Persist a credential in a password manager. |
| Sign | Produce a cryptographic digital signature. |
| Verify | Apply a cryptographic signature check. |
Review notes
- The GPG instructions use an existing key first. Key creation is optional and explicit.
- The public export uses
gpg --armor --export; it never exports a private key. - The proof command generated by the form must use
--no-textmode. The downloaded bytes must not change. - The local Git commands use
--local; they do not change the user's global Git configuration. - The approval-key commands were checked against
cf/nerudo-cli/src/main.rs.nerudo pubkeyprints only the public key.nerudo seal --trunk TRUNK_ID --change CHANGE_IDdisplays the change and asks for confirmation. The guide never uses--yes, never replaces an existing key, and requires the existing CLI connection. The developer credential cannot authorize this command. - The developer example uses the actual read route
/v1/repos/OWNER/REPO/api/stateand an environment variable, not a literal secret. - New developer credentials come from repository settings with one fixed repository. Owner settings provide an overview with repository links; they do not create organization identities.
- Account Authorized tools lists and revokes the user's credentials across repositories. Existing credentials with multiple repository scopes remain visible and revocable; their rights do not expand.
- The developer credential authorizes only the selected read/comment operations. It grants no Git transport, approval, landing, administrative, or agent-delegation authority.
- The guides do not state that GPG ownership gives repository access or proves an email address.
- UI labels remain exact product names. Reviewers should update the quoted labels with each form change.
- Organization roles govern organization metadata and management. They do not automatically grant private code access or repository approval rights.
- Organization creation requires a completed signup username and creates the first owner. Existing organizations require explicit operator ownership setup.
- Membership uses stable account IDs; self-leave cannot remove the final active owner. Repository policy roles remain separate after organization membership changes.
- Transfers require authority in both namespaces and a free exact target name. Repository policy membership persists after transfer. All credentials for the source address are revoked, including credentials with multiple repositories. Permanent deletion and archive are not documented as available controls.
Integration guide terms
The Codex guide defines its terms before the procedure. The integration guide uses the account terms above with these additional limits.
| Term group | Meaning and permitted use |
|---|---|
| Agent bearer token | The service operator's AGENT credential for native agent operations. It is not a personal developer credential. |
| Agent key | The secret value for one agent fork. It is not a person's private key. |
| Native MCP server | The Rust server in the Nerudo product repository. MCP means Model Context Protocol. |
| Git terms | Checkout, branch, commit, commit ID, HEAD, trunk, base commit, fork, ancestor, reference, file tree, and commit trailer keep their Git meanings. |
| Nerudo records | Change, revision, task, change context, batch, footprint unit, receipt, landing log, seal, allowance, and release identify Nerudo objects. |
| Software terms | CLI, program, package, source file, entry point, subcommand, Cargo workspace, Rust toolchain, dependency, and compatibility code identify software objects. |
| Configuration terms | Configuration entry, environment variable, process environment, working directory, absolute path, file creation mask, file mode, and credential file identify computer settings. |
| Network terms | API, HTTP request, HTTP header, HTTPS, URL, route, origin, redirect, timeout, JSON, field, boolean, and raw JSON record keep their protocol meanings. |
| Interface text | Tool names, commands, filenames, field names, environment variable names, and result states keep the source spelling. |
These are subject terms under rule 1.5, chiefly category 19. Quoted interface text uses category 10. Names of programs and protocols keep their established spelling. The term groups do not permit ordinary unapproved words in general descriptions.
| Technical verb | Limited process |
|---|---|
| Copy | Put unchanged source text in a local file. |
| Deprecate | Stop new software use of an identifier that remains for compatibility. |
| Fetch | Get Git objects and update a Git reference. |
| Install | Put the CLI package on the computer. |
| Rebase | Apply Git commits to a different base commit. |
| Save | Write a computer value to a local file. |
| Sign | Make a cryptographic signature. |
The verbs use the computer-process category in rule 1.12. The existing account entry for “sign” also applies to cryptographic signatures in the integration guide. Ordinary instructions use approved verbs such as “make,” “get,” “use,” “examine,” and “record.” A developer credential gives no Git transport, landing, approval, administrative, or agent-delegation authority.