# Step-by-Step

Audience: Operators following a full Docker installation, configuration choices and ongoing administration

## s00 · Install the Docker demo · Prepare the Docker host

This film follows the Operations manual, from a prepared Docker host to evidence stewardship. The lens command needs Python 3.9 or newer, Docker and its Compose plugin. Start the Docker engine and use an account that can access it. Use the intended Linux or macOS host. Keep installation files private. Next, copy the lens command onto this host.

```sh
# Prepare a Linux or macOS Docker host
# Python 3.9 or newer
# Docker engine running, Compose plugin installed
```

Sources:
- apps/docs/content/installation/index.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s01 · Install the Docker demo · Copy lens and make it executable

Copy the lens file onto the machine and make it executable. Place it in a new, empty installation directory. Open a terminal there and run chmod plus x lens, as shown. For published images, lens is the only file you need to copy. It writes its embedded Compose files during setup and downloads the application images. Keep the build ID from lens version with your installation notes. Use this directory for every setup and management command. Then run lens doctor. Fix any failed check before continuing.

```sh
# Copy the lens file into a new installation directory
chmod +x lens
./lens version
# Keep the printed build ID with your installation notes
./lens doctor
```

Sources:
- apps/docs/content/installation/quick-start.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s02 · Install the Docker demo · Choose the private network in setup

The setup wizard asks for a private mesh network prefix. Its default is ten dot two three nine dot five eight. Use it only if that range does not overlap your Docker, host or VPN networks. If you are unsure, ask your network administrator for an unused private range. Enter its first three numbers in the wizard. Keep the selected prefix unchanged after records exist.

```sh
# In setup, choose an unused private mesh network
# Default prefix: 10.239.58
# Keep the prefix unchanged after records exist
```

Sources:
- apps/docs/content/installation/settings.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s03 · Install the Docker demo · Run setup and enter registry access

From the directory containing lens, run lens setup. It checks Docker and Compose, then asks for your GitHub login and a personal access token for GitHub Container Registry, or GHCR. The token needs read packages permission and access to the NovusLens packages. Its entry is hidden. The token is not stored in dot novuslens dot env. The installer keeps the registry login in a separate private file, dot novuslens registry dot json, for later starts and resumes. You do not need a separate registry login command. The following recording begins with the installation settings, after registry access.

```sh
./lens setup
# Enter your GitHub login and PAT when prompted
# PAT permission: read:packages
# Registry login: .novuslens-registry.json (private)
```

Sources:
- apps/docs/content/installation/remote.mdx
- apps/docs/content/installation/quick-start.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s04 · Install the Docker demo · Use the default published images

Run lens setup with no options. In a git checkout, it builds local images from that source. Anywhere else, it pulls the published release that this lens file was built for. An existing installation keeps its saved release. You only need an init option to choose another mode or release. Local builds frozen images from a checkout. Dev mounts live source from a checkout. A published version such as zero point one point zero selects a fixed release. The installation records your choice for later commands.

```sh
# Default: ./lens setup
# Advanced choices need an explicit --init option
# --init local, dev or ghcr:0.1.0
```

Sources:
- apps/docs/content/installation/index.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s05 · Install the Docker demo · Choose the port and account

Keep web port three one one one unless another application uses it. The demo binds that port to address one two seven dot zero dot zero dot one. Use a browser on this Docker host. Choose the operator login or keep demo owner. Enter a passphrase of at least twelve characters, then repeat it. Record both in your password manager. The operator can administer every organisation in this installation.

```sh
# First demo choices
Web port: 3111
Operator login: demo-owner
Passphrase: at least 12 characters

# Keep the actual passphrase in your password manager
```

Sources:
- apps/docs/content/installation/settings.mdx
- apps/docs/content/installation/quick-start.mdx

## s06 · Install the Docker demo · Choose the model server and demo

Choose none as the model server for the first run. Then choose retail lending as the demo to load. This fictional example lets you browse a map and import an organisation chart without a model server. Interviews and model-backed questions need a configured model server. Skip the interview steps in this guide until one is available. To add a model server later, run the setup command shown on screen. It asks every setup question again. The Setup settings page explains each model server choice, including OpenRouter and local Ollama.

```sh
# First demo choice
Model server: none
Demo to load: retail-lending

# Available now: map browsing and chart import
# Needs a model server: interviews and model-backed questions

# Add a model server later
./lens setup --interview
```

Sources:
- apps/docs/content/installation/settings.mdx
- apps/docs/content/installation/quick-start.mdx

## s07 · Install the Docker demo · Keep the saved configuration

The wizard saves credentials and settings in dot novuslens dot env. Keep that file private and retain it in the installation directory. Keep your original setup journals and Docker volumes for later runs. Reusing saved configuration preserves the credentials. The project name and mesh addresses identify the existing installation. Keep them unchanged after records have been created. Checkpoint: you have retained the installation files and recorded the operator passphrase securely.

```sh
# Keep these installation files private
.novuslens.env

# Keep the setup journals and Docker volumes
# Keep the project name and mesh addresses unchanged
```

Sources:
- apps/docs/content/installation/settings.mdx
- apps/docs/content/installation/index.mdx

## s08 · Install the Docker demo · Start and sign in

The settings are saved. When ready, run lens start and wait for the printed sign-in address. Open it in a browser on the Docker host. Sign in with your saved operator account. Open Retail Lending and its Guide. With no model server you can browse the map and import a chart. Interviews and model-backed questions need a configured model server. Checkpoint: the organisation and Guide both open.

Sources:
- apps/docs/content/installation/quick-start.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s09 · Install the Docker demo · Inspect progress and resume

After deployment the installer opens its monitor. It shows service health, analysis age, the model server and the setup journal, and leaving it keeps the services running. Run monitor to reopen it, status for setup progress and logs for recent service output. After an interruption, restore any failed prerequisite, then run resume. Completed outputs are checked before reuse. Keep the journals, configuration and volumes intact. If a journal is damaged, preserve it and use the troubleshooting guide’s diagnostic packet for maintainer assessment.

```sh
./lens monitor
./lens status
./lens logs
./lens resume
```

Sources:
- apps/docs/content/installation/quick-start.mdx
- apps/docs/content/operating/troubleshooting.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s10 · Install the Docker demo · Stop and return to the same records

Use stop to shut down this demo. Use start to return to the saved installation. Keep dot novuslens dot env private, retain the journals and Docker volumes, and keep the project name and mesh addresses unchanged. Do not remove volumes to troubleshoot. Stop is not a backup. Run lens backup to take one, and test a restore before relying on it.

```sh
./lens stop
./lens start
```

Sources:
- apps/docs/content/installation/quick-start.mdx
- apps/docs/content/installation/index.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s25 · Docker configuration choices · Choose the release, models and demo

The first demonstration uses published images, no model server and fictional Retail Lending data. Without an init option, a copied lens file pulls the release it was built for. A git checkout builds locally instead. An init option selects another release or source mode. Local builds frozen images from a checkout. Dev mounts live source from a checkout. A published tag such as zero point one point zero selects a fixed release. Later commands run the recorded release. For a new installation, setup suggests OpenRouter, which needs an OpenRouter key. Choose external for an existing OpenAI-compatible model server, or local for Docker-hosted Ollama. Check memory and disk requirements before downloading models. For the demo, choose none for an empty installation. Choose Meridian for its interview-based demonstration, which needs a model server. Use configure to edit saved choices. It starts from your saved answers. Keep the project name, identity salt and mesh addresses.

```sh
./lens configure
# Answer No to reusing saved configuration
# Choose models and demo; retain installation identity
./lens resume

# The release recorded at --init: dev, local or ghcr:<tag>
# Models: openrouter, none, external or local Ollama
# Demo: retail-lending, none or meridian
```

Sources:
- apps/docs/content/installation/index.mdx
- apps/docs/content/installation/settings.mdx
- apps/docs/content/architecture/operations/docker-demo.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s11 · Accounts and organisation import · Use the administration path for your deployment

Run administration commands with lens. It runs them in the running reasoning service, with the saved installation configuration and credentials. It copies each input file you name into the container and passes the new path on. The first operator was created during setup. Check the required role and organisation scope before each action.

```sh
./lens graph create-viewer --help
```

Sources:
- apps/docs/content/operating/operator-shell.mdx
- apps/docs/content/operating/administration.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s12 · Accounts and organisation import · Create accounts with the right role

Create each account with its organisation and role. There is no self-signup. Board accounts read without changing organisational records. Business-unit owners need a cell scope. Operators administer the installation. Replace the example account, organisation and private passphrase on screen. Run the command with lens, then sign in as that account to check its intended access.

```sh
./lens graph create-viewer --viewer YOUR_ACCOUNT --org YOUR_ORG \
  --role board --passphrase YOUR_PRIVATE_PASSPHRASE
```

Sources:
- apps/docs/content/operating/operator-shell.mdx
- apps/docs/content/operating/administration.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s13 · Accounts and organisation import · Import a chart before an interview

Open Administration, then Import. Prepare the organisation chart using the Operations manual’s linked input format in the Product Guide. Choose the chart file and import it. Inspect the resulting organisation map. The chart supplies documented structure at shown. An interview transcript adds statements at told and needs a configured model server. Inspect disagreements before continuing; an interview does not silently rewrite the chart.

Sources:
- apps/docs/content/data/formats/orgchart.mdx
- apps/docs/content/data/formats/interview.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s14 · Knowledge and measured evidence · Bring documents into the knowledge library

Prepare a Markdown document on the Docker host. Place note.md in the installation directory. Replace the organisation, account and title with your intended values. Check its source, related teams and visibility in the knowledge library. Leadership and team contributions have different audience defaults. Review access using an account from the intended audience.

```sh
./lens connectors document --org YOUR_ORG --viewer YOUR_ACCOUNT \
  --title "Board strategy note" --file ./note.md --page org/board
```

Sources:
- apps/docs/content/using/knowledge.mdx
- apps/docs/content/data/formats/documents.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s15 · Knowledge and measured evidence · Connect a source through its mapping

Measured evidence comes from operational sources through customer-authored mappings. A mapping says which records belong to which cells and how raw quantities become indicators. Unmapped groups are reported. They are never guessed into a cell. Simulated sources retain their label. Choose the cookbook for the source type you actually use, then inspect the acquired evidence and its observation dates.

Sources:
- apps/docs/content/data/formats/telemetry.mdx
- apps/docs/content/using/evidence-and-proof.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s16 · Knowledge and measured evidence · Inspect calibration and missing inputs

Open Organisation, then Complexity, change and recovery. Choose a team and its scope. Open Calculation and sources under each indicator. Complexity, Agility and Recoverability use explicit local calibration. Read the formula, inputs, source and validity period. If a rule or required input is absent, keep the indicator unknown. Discuss the mapping with the customer before treating values as comparable.

Sources:
- apps/docs/content/using/car.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s17 · Agents and stewardship · Read an agent’s published declaration

Agent inventory records say what each agent may do and who answers for it. The source and any attestation determine its evidence basis. Inspect the declaration beside observed activity in AI agents. For product declarations, the operator first enrols the product source and names permitted remit issuers. Read the Guide’s exact source enrolment steps before activating it.

Sources:
- apps/docs/content/using/ai-agents.mdx
- apps/docs/content/operating/day-one-agents.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s18 · Agents and stewardship · Record a remit with the responsible person

After source enrolment, open Declare a remit. Select the agent and record its purpose, responsible role and authority basis. List operations, resources, destinations and any exclusions. Mark the list complete only if it is complete. Select Save draft. An enrolled issuer selects Approve. They must own the agent’s cell or be the accountable executive. Operators use On behalf of for that person’s recorded approval.

Sources:
- apps/docs/content/using/ai-agents.mdx
- apps/docs/content/operating/day-one-agents.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s19 · Agents and stewardship · Refresh evidence within its support window

Inspect source dates and the current-support line. A boundary feed supports findings for three refresh intervals after its entry was written. Schedule acquisition more often than that window. After support lapses, affected findings are withheld until fresh evidence supports them again. A stopped estate is not evidence. Any simulated estate keeps its label when its findings reach the product.

Sources:
- apps/docs/content/using/ai-agents.mdx
- apps/docs/content/operating/day-one-agents.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s20 · Agents and stewardship · Retract with a reason and inspect the audit

Stewardship actions require an authorised identity and a reason. Retraction withdraws a record from surfaces while preserving who acted, when and why. Purging an evidence body leaves a tombstone. Forgetting an organisation is a separate erasure procedure with wider consequences. Choose the Guide page for the action you intend. Inspect the receipt, then open Activity log to confirm the recorded action.

Sources:
- apps/docs/content/operating/administration.mdx
- apps/docs/content/using/activity-log.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s21 · Agents and stewardship · Read a coherence sweep’s completion status

A deep coherence sweep compares knowledge statements with a snapshot of graph facts. Proposed contradictions receive two independent judgements. Unsettled proposals remain marked unresolved for human review. Inspect evaluated and unevaluated counts and whether the report is complete, partial or failed. A sweep that raises nothing is not proof of consistency. Model-backed sweeps require your configured model service.

Sources:
- apps/docs/content/operating/administration.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s22 · Notifications and recovery · Inspect delivery without assuming action

Subscribe an approved receiver using your operator login and organisation. A subscription alone does not deliver notices. Run notify poll with that login and the printed browser base address, including your chosen web port, then inspect notify deliveries. Docker does not schedule polling. Arrange ongoing delivery with the installation owner. Check the receiver allow-list first. A recorded delivery outcome does not prove that someone read or acted on the notice.

```sh
./lens connectors notify subscribe --org YOUR_ORG --viewer YOUR_OPERATOR \
  --endpoint https://receiver.example/hook --kind fleet-incident
./lens connectors notify poll --org YOUR_ORG --viewer YOUR_OPERATOR \
  --base-url YOUR_BROWSER_BASE_URL
./lens connectors notify deliveries --org YOUR_ORG --viewer YOUR_OPERATOR
```

Sources:
- apps/docs/content/operating/administration.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s23 · Notifications and recovery · Plan Docker recovery before relying on the demo

Stopping and starting again preserves Docker volumes. Recovery from losing those volumes needs a backup. The lens command has backup and restore commands. Backup pauses the three mesh nodes briefly, then archives the database, all three mesh volumes, setup journals, release information and the private configuration file. The archive holds the secrets, so only your user can read it. Keep each archive private, and store a copy away from the host. Restore needs no earlier setup: when the installation has no configuration file, it puts the archive's copy in place. Restore refuses a mismatched release or configuration file, keeps a backup of the current state, and restores both stores together. Test a restore before relying on the installation.

```sh
./lens backup
# Archive: database, three mesh volumes, journals, release data, .novuslens.env
# The archive holds the secrets; keep it private
# Test ./lens restore before relying on it
```

Sources:
- apps/docs/content/operating/backup-restore.mdx
- apps/docs/content/installation/index.mdx
- apps/docs/content/manuals/operations-manual.mdx

## s24 · Notifications and recovery · Collect evidence before asking for help

For a Docker problem, retain the installation directory and run status and logs. Record the release identity, failed step and exact error. Use Collect a diagnostic packet in the troubleshooting guide. Remove credentials and organisational data before sharing it with your demo provider. For model-backed failures, check the configured endpoint and available models. Finish by signing in and checking the expected records again.

```sh
# Record the lens build and saved release
./lens version
./lens status
./lens logs
```

Sources:
- apps/docs/content/operating/troubleshooting.mdx
- apps/docs/content/manuals/operations-manual.mdx