Accounts and stewardship, who may act, and who is recorded.
Run every command on this page from the installation directory.
What you will achieve
Use this page to manage accounts and choose each person’s role. It also explains record changes, the audit trail, notifications and erasing an organisation. Accounts are the only identity the platform recognises. Everything in the audit trail names a signed-in account.
What it is for
A twinTwinNovusLens’s model of one organisation, built from records about its teams, services and how they rely on one another. It is only as current as those records. holds sensitive evidence about people and their work. The customer’s stewards decide who may see it and who may change it. The platform records every read and action against the account that made it. Keep accounts current so those records identify the responsible person. Keeping that list correct is an operator task.
Before you start
- The installation is running. Setup created the first operator account; see Setup settings.
- You know the account name, the role, and the organisation (or
*for the operator account) you want to create.
Steps
1. Create or change an account
Two commands manage accounts. Both run in this installation’s reasoning service, with its configuration, on its private network. create-viewer makes a new account and refuses a name that already exists:
./lens graph create-viewer --viewer <account> --role <role> --org <org> \
[--scope-cell <cell>] [--passphrase <value>]update-viewer changes an existing account and refuses a name that does not exist. Give only the flags you want to change:
./lens graph update-viewer --viewer <account> [--role <role>] [--org <org>] \
[--scope-cell <cell>] [--passphrase <value>]The flags are these. --viewer is the account name. --role is one of the five roles below. --org is the organisation the account works in, or * for the operator. --scope-cell applies to the business-unit owner role and names the root of the subtreeSubtreeOne unit and every unit nested beneath it in the organisation's hierarchy. the account may see. --passphrase sets the login credential; the platform stores only a saltedSaltExtra data mixed into a value before its fingerprint is calculated. It makes matching or guessing the original value harder. hashHashA fixed-length fingerprint calculated from content. Comparing fingerprints helps detect changes and match records. of it, using PBKDF2-SHA256PBKDF2-HMAC-SHA256The password-storage method used here. It repeatedly mixes the passphrase with extra random data to make guessing stored passphrases more expensive.. For create-viewer, omit --passphrase and the account is created with no credential, so it cannot sign in until update-viewer sets one. For update-viewer, omit --passphrase to leave the credential as it is; update-viewer refuses a call that gives no change flag. The passphrase is on the command line, so your shell history and the process list can record it. Set a temporary passphrase, hand it over privately, and set the one the person chooses with update-viewer. A missing required flag or an unknown role is refused on the host, before Docker runs. Add --help to either command for its flags.
Each command prints the account, its role and organisation, and whether the credential was set or left unchanged.
2. Choose the role
| Role | Who it is for | What it may do in the platform |
|---|---|---|
cxo | an executive for one organisation | reads the organisation’s picture; performs the stewardshipStewardshipCare of recorded information, such as correcting or withdrawing entries. The action allowed depends on the record type and the reader’s role. actions for the organisation (see step 3); reads the audit trail |
bu-owner | the owner of one business unit | scoped to the subtree named by --scope-cell; may write where the endpointEndpointA particular address on a service that accepts a defined kind of request. allows a non-board writer |
infra | the operator of the estate’s infrastructure | reads and writes where the endpoint allows a non-board writer |
operator | the platform operator, for every organisation (--org '*') | performs every steward act; reads the audit trail for all organisations |
board | a board member | read-only; may read the audit trail, which shows the kind of each action and withholds the term or target a colleague typed |
A board account cannot write. The platform refuses any write from a board account.
3. Stewardship actions
The stewardship actions are the stewardship endpoints of the reasoning service. They are reached through the web application’s reasoning proxyProxyA service that receives a request and forwards it to another service. The NovusLens web proxy adds the signed-in identity and service token.. Each checks the account’s role on the server.
| Act | Endpoint | Who may perform it |
|---|---|---|
| Set the visibility of a meaning entryMeaning entryA stored written account supplied by the organisation, such as a policy or definition. Answers can cite it without treating it as a measured fact. | POST /meaning/visibility | the entry’s ingester, the organisation’s cxo, or the operator; board accounts cannot write |
| Retract a meaning entry | POST /meaning/retract | the entry’s ingester, the organisation’s cxo, or the operator; board accounts cannot write |
| Retract a findingFindingA difference in the records that needs a decision. It includes its sources and can describe a slow handoff, disputed fact or missing owner. | POST /steward/retract-finding | the organisation’s cxo, the operator, or the speaker who made the finding |
| Retract a session | POST /steward/retract-session | cxo or operator only; the transcript is purgedPurgeRemoving a stored document’s contents while keeping a record that it was removed and why. Conclusions that used it must be checked again. |
| Purge an artefactArtifactA stored source file or evidence body that a record can cite. Keeping the exact content lets a reader check what supported the record. | POST /steward/purge-artifact | cxo or operator only |
| Deep sweepDeep sweepAn on-demand review that uses AI models to look for contradictions between written entries and the organisation model, or between written entries. | POST /steward/deep-sweep | cxo or operator only |
| Read the audit trail | GET /steward/audit | cxo, board or operator |
A refused session retractionRetractionThe withdrawal of a finding or meaning entry, with the reason recorded. The record keeps who withdrew it, when and why; it is not deleted. is itself recorded in the audit trail as a refusal, so an attempt that failed is still visible.
4. Read the audit trail
The audit trail is GET /steward/audit. It accepts viewer and limit (default 100, clamped to 1 to 500), and the optional filters person, role, org, action, since and until. Every read and every action is recorded, so the trail answers who looked at what, and who changed what, and when. A cxo account sees the entries made by accounts of its own organisation. The operator sees all of them.
5. Notifications
A notification subscription tells a named webhookWebhookA web address that receives a message automatically when an event occurs. NovusLens notifications send record identifiers there. about findings of the chosen kinds. Use the operator login chosen during setup in every notification command:
./lens connectors notify subscribe --org <org> --viewer <operator-login> --endpoint <url> --kind <kind>
./lens connectors notify list --org <org> --viewer <operator-login>
./lens connectors notify deliveries --org <org> --viewer <operator-login> --limit 20Subscriptions do not schedule delivery. Run ./lens connectors notify poll --org <org> --viewer <operator-login> for one delivery pass. Or keep ./lens connectors notify watch --org <org> --viewer <operator-login> running in a terminal you manage. For either command, set --base-url to the browser address for this installation, including its web port.
The other notify subcommands are remove, poll and watch. remove marks a subscription as removed. poll makes one delivery pass. watch repeats it at regular intervals; --interval defaults to 60 seconds. The platform refuses an endpoint whose host is a cloud metadata name or ends in .internal. It also refuses a link-local address and a loopbackLoopbackA network address that refers to the same host, such as 127.0.0.1. Other hosts cannot reach a service through that address. receiver (localhost or a loopback address). Inside the installation, a loopback address is the service’s own containerContainerA running program with its own packaged software and isolated environment, managed by Docker on the host., so give the receiver’s network address. Redirects are not followed.
A delivery that fails is retried up to eight times in total. The waits between attempts are one minute, five minutes, fifteen minutes, thirty minutes, one hour, two hours and four hours. After the eighth attempt the delivery stops.
6. Forget an organisation
Forgetting an organisation is the one erasure act. The installation must be running, because the command runs in its reasoning service:
./lens forget-org <org> --reason '<why>' --yesThe command deletes the organisation’s read modelRead modelThe database tables used by the map, Ask and Find. NovusLens rebuilds these tables from its history of recorded changes., evidence bodies, sealed identity joinSealed identity joinStored links between employee fingerprints and teams or services. The fingerprints replace readable employee identifiers. Product pages do not show the links for individual people., agentAgentA program that takes actions for an organisation. NovusLens records what it is allowed to do and what its activity reports show. evidence, meaning entries, notifications, accounts, and the audit rows those accounts wrote. It runs in one transactionTransactionA group of database changes that is saved together. If the group fails, its changes are not saved. and records one audit row with the actor operator and your reason. It marks the organisation as forgotten to prevent accidental rebuilding. The materialiserMaterialiserThe component that reads recorded changes in order and updates the database. It records its place so it can continue after a restart. refuses to rebuild a forgotten organisation, and an import refuses its identifier at the first check. To import the organisation again, give it a new identifier.
The canonical logCanonical logThe permanent history of changes to an organisation’s model. New entries are added at the end. Earlier entries stay when the database is rebuilt. in the meshMeshA set of connected Mycelium services that exchange updates and keep the NovusLens log. volumes is append-only and still carries the organisation’s commits. Erasing those means removing the mesh volumes, which hold every organisation’s log. That is a decommissioning decision for the customer, not a step this command takes.
What you will see
The account commands print one line for each account change. A forget-organisation run prints forgot '<org>': with the rows deleted from each table, then what is still present. An account that signs in with a wrong credential is refused with one indistinct message, so the platform does not reveal which accounts exist.
When something goes wrong
viewer '<account>' already exists. create-viewer only creates. The account is there. Run./lens graph update-viewer --viewer <account> …with the flags to change.viewer '<account>' does not exist. update-viewer only changes. There is no such account. Run./lens graph create-viewer --viewer <account> --role <role> --org <org> ….update-viewer refused: nothing to change: give at least one of --role, --org, --scope-cell, --passphrase. Add the flag you want to change.Erasure cannot be undone. Add --yes to confirm.Add--yesonce you have confirmed the organisation and the reason. The command deliberately requires both.Give the reason the audit trail will record.Add--reasonwith the reason the customer agreed.Neither reasoning nor projector is running.Run./lens resume, then run the command again.A loopback receiver needs NOVUSLENS_ALLOW_LOOPBACK_WEBHOOK=1 in the deployment. The endpoint islocalhostor a loopback address, which inside the installation is the service’s own container. Give the receiver’s network address instead.- A steward act returns
403. The account’s role is not on the act’s list in the table above. Check the role with the customer before changing it.