Configuration files, and the code that reads them.
NovusLens keeps release versions, the in-product GuideGuideThe help pages inside NovusLens. They explain the pages, input formats and tasks in the version you use. They are product instructions, not evidence about the organisation., rules and test sets in files tracked with the code. Secrets are not among them. The installation’s settings file is separate, and it is covered below by name only.
The files under config/
Most of these files are read by a script or by an image build. Two take effect while the product runs.
The reasoning service and the UI both read finding-scope.json. The init service loads guide.json into
the database when the installation starts.
| File | What it holds | Who reads it | Notes |
|---|---|---|---|
config/README.md | An index to the directory and the reasons for the pins. | People only. | Says “nothing here is runtimeRuntimeThe software that runs a model or agent. A model runtime answers model requests; an agent runtime carries out the customer's agent actions. config”. Several files here now take effect at run time or at launch, so the statement is out of date. |
config/pins.md | The registry of pinned versions: the MyceliumMyceliumThe application infrastructure underneath NovusLens. Its connected services exchange updates and keep the ordered structural log. tag and commit, the SDKSDKSoftware development kit: a package of code that helps another program use a service. NovusLens uses mycelium-py to talk to Mycelium., the sidecarSidecarA separate supporting process that runs beside the application. Here it runs Mycelium and exposes the gateway that NovusLens calls. topology and the toolchains, with the reason for each. | People. Code refers to it in comments, for example apps/mesh/src/conway_mesh/__init__.py. | Prose. The machine-checked values are in release-manifest.json. |
config/mycelium.pin | One line: the full commit SHAGit commitA recorded set of changes. In a software repository it identifies a code version; in the twin log it records a change to the model or its evidence. of the Mycelium release that the sidecar and the Python SDK are built from. | The meshMeshA set of connected Mycelium services that exchange updates and keep the NovusLens log. image build (deploy/docker/mycelium.Dockerfile) fetches this commit and builds the sidecar from it. ./lens ops --version dev sidecar copies that sidecar for the development gates. | The checkout at MYCELIUM_DIR is only the archive sourceSourceA document, interview statement, measurement or export that supports a value. Each source has a date and a stated scope.. It is not what gets built. |
config/release-manifest.json | The identity of the release used for the release checks. It records the Mycelium tag and SHA, the SDK version and wheelWheelA packaged Python library ready to install. A vendored wheel is stored in this repository so its exact bytes can be checked. hashHashA fixed-length fingerprint calculated from content. Comparing fingerprints helps detect changes and match records., and the sidecar hash. It also records toolchain versions, the schemaSchemaThe declared structure of data: which fields or tables exist and which values they accept. head, local modelLanguage modelSoftware that produces text from instructions and supplied context. NovusLens checks its answers against the records retrieved for the question. names and the candidate tag. | The application image build, where deploy/docker/verify_sdk.py refuses a wheel whose hash differs. ./lens backup stores a copy in the archive. scripts/build_guide.py reads the release label. deploy/bundle.sh and ./lens ops also read it. | Recorded on a deliberate re-pin only. It is a record, not a live status. The top-level keys are candidate, mycelium, sdk, sidecar, toolchains, schema and models. |
config/guide.json | The in-product Guide: a release label, a content hashHashA fixed-length fingerprint calculated from content. Comparing fingerprints helps detect changes and match records. and the list of Guide pages. Each page has an id, title, section, audience, summary and body. | Written by scripts/build_guide.py. Loaded into PostgresPostgresThe database software that stores the tables read by the NovusLens screens, along with document bodies, access records and protected personnel records. by the init service (deploy/docker/bootstrap.py) each time the installation starts. The Guide test reads it. | Generated from authored apps/docs/content/guide/*.mdx; docs/guide/*.md is frozen provenanceProvenanceThe record of where a value came from, who stated it and when. Every value keeps this record.. Do not edit the JSONJSONJavaScript Object Notation: a text format for data, using named fields, lists and values. Configuration files and service messages use it. by hand. Rebuild it after you change a Guide page. The Guide is product copy, not evidence. |
config/finding-scope.json | The rules for who may see a finding. It has the estate-only kinds, the keys that name an edge or 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., the wording for partial edges, and 21 parity cases. | Read at run time by packages/common_py/src/common_py/finding_scope.py and apps/ui/lib/findingScope.ts. Both are tested against the same cases. | The Python and TypeScript implementations must agree. Unknown 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. is treated as narrow, never as broad. |
config/answer-eval.json | The answer evaluation set: 13 questions across three viewers, each with paraphrases, what a correct answer must and must not do, and the thresholds. The thresholds include zero leaks, zero false absences, and a limit of 0.25 on the share of insufficient answers. | scripts/answer_eval.py, run by ./lens ops --version dev answers. | Runs against the local model on demand. It is not one of the twelve release checks. Reports go to docs/gates/answers/. |
config/audit-triage.json | A list of dependencyDependencyA link where one unit needs something from another. A dependency is not a reporting line: it shows where work relies on something else. advisoriesAdvisoryA published report of a security problem in a software package. the release accepts, each with a reason. It includes accepted advisories and their recorded status. | packages/common_py/src/common_py/audit_gate.py, called from the test gate in ./lens ops. | The test gate refuses any advisory not listed here. Read the file for the accepted advisory IDs, their status and the reason for each decision. |
config/regions.md | A design note on regions. Each region is one Mycelium clusterClusterA group of computers running together as one installation. Each regional NovusLens installation keeps its own records., and a region’s signed federation factsDigital signatureA check calculated with a signing key that can detect whether a record has changed. Identifying the signer also requires a trusted link between that key and its owner. are the only data that crosses a boundary. It names three regions and describes the Ed25519Ed25519The digital-signature method used to sign evidence. The private key signs the exact content; the public key checks that signature. identity key each one has. | Nothing in the code reads it. | A design note. It describes a test setup that models the three regions using one physical mesh and one database. |
The installation’s settings file
./lens setup writes .novuslens.env in the installation directory. Docker ComposeDocker ComposeThe Docker tool that starts and connects the services listed in one configuration file. reads it and passes each service only the variables compose.yml names.
Every ./lens command checks the file before it runs, and refuses a missing line, a line it does not know or a development value.
Setup settings describes each line. Environment variables gives what each service reads. The table below names the lines only, grouped by purpose. Values are not shown.
| Group | Names | Notes |
|---|---|---|
| Secrets | POSTGRES_PASSWORD, CONWAY_SESSION_SECRET, CONWAY_IDENTITY_SALT, CONWAY_SERVICE_TOKEN, MYCELIUM_GATEWAY_TOKEN | Setup generates each once. Never change the database password or the identity saltIdentity saltA secret value added before employee identifiers are turned into fingerprints. Keep the same value so later imports can still match existing people.. Secrets explains how to change the others. |
| Installation | CONWAY_PROFILE, COMPOSE_PROJECT_NAME, COMPOSE_PROFILES, NOVUSLENS_INSTALL_DIR, NOVUSLENS_MESH_NETWORK | CONWAY_PROFILE must be customer. The project name names the containersContainerA running program with its own packaged software and isolated environment, managed by Docker on the host. and volumes. |
| Images | NOVUSLENS_IMAGE_PREFIX, NOVUSLENS_IMAGE_TAG, NOVUSLENS_IMAGE_SOURCE | The release the installation runs, and whether its images are pulled or built. |
| Web application and analysis | NOVUSLENS_UI_PORT, NOVUSLENS_PROJECTION_INTERVAL | The web port, and the seconds between background analysis passes. |
| Network access | NOVUSLENS_TLS_PROXY, NOVUSLENS_UI_BIND | Present only when you choose an HTTPSHTTPSHTTP carried over an encrypted connection, so the contents are protected while travelling between the caller and the server. proxy. Network access explains them. |
| Advanced | CONWAY_OBSERVATION_TTL_DAYS, NOVUSLENS_WEBHOOK_ALLOWLIST, NOVUSLENS_MCP_EXPOSE | Present only when you change one from its default. |
| Demo and first operator | NOVUSLENS_DEMO, NOVUSLENS_MERIDIAN_DEMO, NOVUSLENS_ADMIN_VIEWER, NOVUSLENS_ADMIN_PASSPHRASE | Read by the init service. |
| Model server | CONWAY_LLM_ENDPOINT, CONWAY_BUILD_MODEL, CONWAY_COMPASS_MODEL, CONWAY_LLM_API_KEY | The APIAPIApplication programming interface: a defined way for one program to request data or actions from another. key is sent only to OpenRouter’s endpointEndpointA particular address on a service that accepts a defined kind of request.. |
Database migrations
The migrationsMigrationAn ordered change to a database's tables or rules. Applied migration files are recorded so the same file is not run again. live in apps/graph/migrations. apps/graph/src/conway_graph/db.py applies the files that
are pending, in filename order, and records each one in schema_migrations. Migration 0016 removes the
development viewers and seeds none, so a product install gets its viewers only through the product. The
table below gives the main effect of each file. Column additions and index names are summarised, not
listed in full. Open the file for the exact statement.
| File | What it creates |
|---|---|
0001_init.sql | The read modelRead modelThe database tables used by the map, Ask and Find. NovusLens rebuilds these tables from its history of recorded changes.: cells, cell_car, attribute_provenance, edges, cell_lineage, findings, materialiser_cursor, twin_cpl, twin_fidelity and query_audit, with search indexes. |
0002_m3_fresh_org.sql | evidence_artifacts and sealed_identity_join, with their indexes, and the cell_headcount function. |
0003_m4_interrogation.sql | scenarios and actor_map, the account and role table. |
0004_operational_surface.sql | artifact_requests. |
0005_unknown_coupling_and_org_meta.sql | org_meta. |
0006_cell_aliases.sql | cell_aliases. |
0007_sovereignty_federation.sql | groups, group_members and federation_facts. |
0008_agentic_overlay.sql | Widens the cells kind check so customer agents can be mapped as cells. No new table. |
0009_s2_hardening.sql | pending_proposals. |
0010_domain_beside_team.sql | domains and cell_domains. |
0011_org_isolation_hardening.sql | materialiser_quarantine, and indexes on findings and federation_facts. |
0012_personnel_idempotent.sql | A unique index so each person has one row per organisation. Removes duplicate rows first. Replaces cell_headcount. |
0013_cell_service_type.sql | A nullable service_type column on cells. |
0014_fact_source_join.sql | artifact_id and locator columns on edges and attribute_provenance. |
0015_domain_owner.sql | An accountable_owner column on domains. |
0016_no_org_viewer_seeding.sql | Deletes the development viewers from actor_map. Seeds none. |
0017_login_and_board_role.sql | A passphrase_hash column on actor_map, and a widened role check that includes board. |
0018_stewardship.sql | Adds a retracted status to findings. Allows evidence_artifacts.body to be null, and adds purgePurgeRemoving a stored document’s contents while keeping a record that it was removed and why. Conclusions that used it must be checked again. columns. |
0019_meaning_layer.sql | meaning_entries, with its page, cell and search indexes. |
0020_timeline_economics_regulation.sql | twin_history, regulations and cell_regulations. |
0021_key_person_risk.sql | critical_path_owner_count. |
0022_integrity_and_observation_windows.sql | materialiser_applied, and a correction_epoch column. |
0023_executive_evidence.sql | responsibility on cells, and provenance and ingested_at on cell_car. |
0024_retained_questions.sql | question_requests, with an index on the viewer’s organisation. |
0025_history_record_changes.sql | record_state and changes (JSON) on twin_history. |
0026_car_assessment_evidence.sql | car_assessment_evidence, which points to the evidence bodies. |
0027_car_axis_observations.sql | car_axis_observations. |
0028_agent_evidence_records.sql | agent_evidence_outbox, agent_evidence_batches, agent_evidence_records and agent_evidence_subject. |
0029_agent_evidence_delivery.sql | agent_evidence_delivery. |
0030_agent_evidence_policies.sql | agent_evidence_policies and agent_evidence_policy_time. |
0031_agent_evidence_cursors.sql | agent_evidence_cursors and agent_evidence_cursor_head. |
0032_boundary_evidence_heads.sql | boundary_evidence_heads. |
0033_notification_subscriptions.sql | notification_subscriptions and notification_deliveries, with a time index. |
0034_external_unknown.sql | Makes cells.is_external nullable with no default, so an externality that was not stated can be recorded as not stated. |
0035_projection_and_recovery.sql | projection_runs, with an index for the latest run per organisation. |
0036_operational_owner.sql | An operational_owner column on cells. |
0037_privacy_floor_five.sql | Raises the cell_headcount privacy floorPrivacy floorThe rule that a unit with fewer than five mapped people is shown as a small team, never as a number. The key-person finding says fewer than five and never says who. from three to five; adds forgotten_orgs. |
0038_fidelity_excluded_infra.sql | An excluded_infra_slots column on twin_fidelity. |
0039_guide_pages.sql | guide_pages, which holds the in-product Guide. |
0040_projection_stages.sql | A stages (JSON) column on projection_runs. |
0041_remit_authoring.sql | product_sources, remit_templates and remit_declarations, with indexes. |
0042_catalogue_deployment_export.sql | activity_catalogues and remit_exports. |
0043_remit_consolidation.sql | A unique index so each subject has at most one approved declaration. |
0044_remit_declaration_cell.sql | A cell column on remit_declarations. |
0045_people_export_snapshot.sql | An index on sealed_identity_join for people-export snapshots. |
0046_people_exports.sql | people_exports, the export ledger. |
0047_people_withdrawal_index.sql | An index on sealed_identity_join by team. |
0048_dependency_conflict_ends.sql | Updates existing findings rows so a dependency conflict names both ends. No new table. |
0049_finding_aliases.sql | finding_aliases, with an index on the successor. |
0050_question_scope.sql | A question_scope (JSON) column on question_requests. |
0051_network_flow_observations.sql | network_flow_observations, with a cell index. |
Each time the init service runs, it checks that every migration in the image is recorded in
schema_migrations. When one is missing, it applies the pending migrations. A backup restored into a newer
release gets its pending migrations this way.
Last updated