Documents, cited beside the graph and never part of it.
A document is a policy, a runbook, a board note or a briefing. It goes into the knowledge libraryKnowledge libraryThe organisation’s written procedures and definitions. Each entry records its source, date and who can read it. NovusLens cites these entries as supplied information. as one call. The library stores it as 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.: a written account the organisation provides. Answers can cite the entry, and the citation resolves to the stored sourceSourceA document, interview statement, measurement or export that supports a value. Each source has a date and a stated scope.. A document never changes a cellCellA box on the map that stands for a team, service, supplier or AI agent. It is a unit you can inspect, not necessarily a department or a person., an edge or a score. Its only effect is on what an answer can cite.
A document lands at the shownShownEvidence that a document supports a value. A recovery plan that states a target shows the target, but it does not show that the target was achieved. rungRungOne of three levels of support for a recorded value: told, shown or measured. The level appears beside the value., because something written backs every entry and the citation resolves to it.
What it carries
A document carries a title, the text as Markdown, and the cells it concerns. It also carries a grouping page, extra named values, a visibility setting, and optional links to earlier entries. The text is stored as an evidence artefactArtifactA stored source file or evidence body that a record can cite. Keeping the exact content lets a reader check what supported the record., so a citation can resolve to the exact source.
Headings and lists survive. Images do not.
Docker commands
For the Compose installation, run commands from the installation directory that holds .novuslens.env and compose.yml.
Prepare the input described below, then import it with ./lens, which uploads the document into the running reasoning containerContainerA running program with its own packaged software and isolated environment, managed by Docker on the host.:
./lens connectors document --org harbour --viewer <account> --title "Customs filing standing order 12" --file so-12.md --cell customs --page customs/policiesUse your organisation id and the chosen account wherever a command asks for them.
Follow the complete Operations manual for accounts, configuration and command access.
Before you start
You need the installation running, and the document’s text saved as a Markdown or plain text file. You also need the account id of the person importing it. The viewer’s position decides the default visibility, so the id matters.
The ingestIngestRead supplied records or documents and add their information to NovusLens, after the required checks. route runs on the reasoning service. Its default address is http://127.0.0.1:8500. The command does not need the service to be reachable, because it calls the same ingest function in-process.
Two ways to send it
The command
The command is the operator’s path. Run it from the installation directory. ./lens copies the --file into the running installation:
./lens connectors document --org harbour --viewer cxo-harbour --title "Customs filing standing order 12" --file so-12.md --cell customs --page customs/policiesThe command takes --viewer, --title and --file as required. The --file value is read as text. It also takes these, each optional:
| Flag | What it does |
|---|---|
--cell | A cell the document concerns. Repeatable. |
--page | A grouping path, such as org/board. |
--attribute KEY=VALUE | A key-valueKey-value storeStorage where a named key points to a value. Reading that key retrieves the value currently stored under it. pair kept with the entry. Repeatable. |
--visibility | A JSONJSONJavaScript Object Notation: a text format for data, using named fields, lists and values. Configuration files and service messages use it. value. Leave it out to take the default derived from the viewer. |
--supersedes ENTRY_ID | An entry this document replaces. Repeatable. |
--based-on ENTRY_ID | An entry this document rests on. Repeatable. |
The command does not take an agent_request_ids value. That field is available only on the route.
On success the command prints the title, the new entry id, the viewer, and the visibility the entry received. If the document replaced earlier entries, it prints which ones were retracted.
The route
POST /meaning/ingest serves the web application and other services on the installation’s private network.
It needs the installation’s service tokenService tokenA secret value sent with requests between NovusLens services. The receiving service refuses requests with a missing or wrong value.. The reasoning service does not publish port 8500 to the host, so an operator uses the command above.
The route takes the same fields as the JSON body described below. The command and the route run the same function, so they accept the same content.
Fields
| Field | Required | What it is |
|---|---|---|
viewer | Yes | The ingesting person. Visibility derives from this person’s position. |
org | Yes | The organisation the document belongs to. |
title | Yes | The document’s name, as people say it. |
body_md | Yes | The text, as Markdown. |
cell_ids | No | The cells the document concerns. An id the graphGraphA model made of units and links between them. In NovusLens it records teams, services and their dependencies. does not hold raises 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. rather than being dropped. |
page | No | A grouping path, such as org/board or grid-ops/runbooks. |
attributes | No | Free key-value pairs kept with the entry. |
visibility | No | Omit it to take the default. Preview the default with the visibility-preview route before ingesting something sensitive. |
agent_request_ids | No | Links to the ask that solicited the document. Route only. |
meaning_entry_ids | No | Entries this document rests on. A support dependencyDependencyA link where one unit needs something from another. A dependency is not a reporting line: it shows where work relies on something else.. |
supersedes_entry_ids | No | Entries this document replaces. |
source_filename | No | The file name stored with the source. The command sets it from --file. |
The route’s model is the one the guide’s examples are checked against. A document with no visibility key is the default case.
Worked example (illustrative)
The organisation below is an example. It is not a real customer.
{
"viewer": "cxo-harbour",
"org": "harbour",
"title": "Customs filing standing order 12",
"body_md": "## Purpose\nDeclarations are filed by the customs desk. The pre-fill assistant drafts; a person files.\n\n## Limits\nNo filing without a named officer's approval.",
"cell_ids": ["customs"],
"page": "customs/policies"
}Visibility defaults from who ingests. An executive’s import is visible to the executive and board only. A cell owner makes it visible to the named cells and their management chain above them. Widening visibility later is an audited act. The visibility-preview route shows the default before you send.
Replace, rest on, or retract
A revised document is a new entry. Its identity comes from the organisation, the page, the title and a hashHashA fixed-length fingerprint calculated from content. Comparing fingerprints helps detect changes and match records. of the body text. Version 2 has different text, so it never overwrites version 1 by itself. Sending version 2 alone leaves both current. You must say which relationship you mean.
The entry id also includes the dependency records of the entries it rests on and the agentAgentA program that takes actions for an organisation. NovusLens records what it is allowed to do and what its activity reports show. requests it cites. The same text under a different set of dependencies is a different entry.
| You want | Field or route | What happens to the earlier entry |
|---|---|---|
| Version 2 replaces version 1 | supersedes_entry_ids: ["<v1>"] | Retracted, reason superseded by <v2> recorded, link kept both ways; gone from every read |
| A commentary that rests on a policy | meaning_entry_ids: ["<policy>"] | Untouched; the commentary is held if the policy is later retracted |
| Remove a document with no successor | POST /meaning/retract with a reason | Retracted with the reason; nothing erased |
The command form takes --supersedes <entry id> and --based-on <entry id>, each repeatable. The entry id is printed when a document is ingested, and it is shown on the meaning page.
Only the entry’s ingester, or the steward, may replace or retract it. The code treats the cxo and operator roles as the steward. Invisible and missing predecessors receive the same refusal. This prevents the response revealing entries outside the viewer’s scopeScopeThe work, data, activity or access that a rule, statement or calculation covers. For access, it names the records an account can see. For team measures, “Own operations” covers the selected unit. “Including descendants” adds the units beneath it..
Worked example: policy version 2 (illustrative)
Version 1 is ingested and prints its id, say 2f9c…. Version 2 replaces it:
{
"viewer": "cxo-harbour",
"org": "harbour",
"title": "Customs filing standing order 12",
"body_md": "## Purpose\nDeclarations are filed by the customs desk.\n\n## Limits\nNo filing without a named officer's approval, recorded in the filing log.",
"cell_ids": ["customs"],
"page": "customs/policies",
"supersedes_entry_ids": ["2f9c…"]
}Afterwards a search for the standing order returns version 2 only. Version 1’s row keeps who retracted it, when, and superseded by <v2>. An answer that cited version 1 is rechecked when opened and says its support changed. Had version 2 been sent with meaning_entry_ids instead, both versions would still be current and an answer could cite either.
What you will see
The command prints ingested '<title>' as <entry id> by <viewer> → visible: <visibility>. It adds the superseded entries if there are any. An unknown cell id raises a finding and a warning. Correct the id or retract the document.
On the meaning page, the entry appears under its page, with its visibility, its ingester and its source. The citation links to the stored file.
Refusals and failures
- Board viewer. Refused. The board reads these records and cannot change them.
- Cells outside the viewer’s scope. Refused. An entry may name only cells the viewer can see.
- Replacing an entry that cannot be replaced. A missing, retracted or invisible predecessor is refused with one message. The route returns a 409.
- Replacing and resting on the same entry. Refused. An entry cannot both rest on and replace the same predecessor.
- Invalid values. A value the route rejects returns a 400. The command prints the error as a Python traceback, not as a short message.
- 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. by someone else. Refused unless the actor is the ingester or the steward.