QiOS DNA Repository

Overview

QiOS DNA is the mirrored documentation filesystem for the live Qi system.

The active model is:

QiAccess -> QiLife -> (QiSystem + QiNexus + QiCapture + QiConnect)

Responsibilities

• Keep every physical folder documented by exactly one _folder.md.
• Keep documentation location-based.
• Keep active system-layer names stable.
• Keep the single-page mirror viewer in site/.

Flows

System folder -> matching QiDNA folder -> _folder.md

Structure

Active system folders:

• 01_QiDNA
• 10_QiAccess
• 20_QiSystem
• 30_QiServer
• 40_QiCapture
• 50_QiNexus
• 60_QiApp_QiLife
• 70_QiConnect

The site/ folder contains the single-page system mirror viewer.

QiOS DNA Chronicle

Generated review export placeholder.

Regenerate this file from Codespaces after the repo structure is stable.

This file is not canonical doctrine by itself.

Codex Reconciliation Brief: QiOS DNA

Purpose

This document is the merged instruction brief for Codex to reconcile the _QiOS_DNA repository without destroying raw imports, losing context, or inventing a new folder doctrine.

Codex should use this as the controlling task document.

1. Locked System Model

The locked local root structure is:

C:\QiLabs\
  .github\
  .qios\
  .vscode\
  00_QiEOS\
  10_QiOS_Start\
  20_QiSystem\
  30_QiServer\
  40_QiCapture\
  50_QiNexus\
    My Drive\
  60_QiApps\
  70_QiConnect\
  packages\
  scripts\
  toolbox\

This repo, _QiOS_DNA, is the portable GitHub documentation/doctrine version of the QiLabs system brain. It should mirror the locked QiLabs root logic, not a generic documentation hierarchy.

2. Layer Definitions

Use these definitions as canon:

QiOS        = whole ecosystem / operating system
QiEOS       = origin brain / doctrine / decisions / receipts / system map
QiOS_Start  = cockpit / launcher / front door / docs surface
QiSystem    = rules / schemas / naming / database doctrine / lifecycle rules
QiServer    = infrastructure / Docker / Cloudflare / deploy / monitoring / backups
QiCapture   = ingestion / OCR / parsing / embeddings / pipelines
QiNexus     = storage backbone / workspace model
QiApps      = standalone apps, sites, tools
QiConnect   = integrations / APIs / workers
packages    = shared code, types, utilities, db helpers
scripts     = thin wrappers only
toolbox     = local tools and power utilities

Important correction: QiOS is not only the interface. The interface is QiOS_Start. QiOS is the whole operating system/ecosystem.

3. Current Doctrine Relationships

Use these module relationships:

QiOS
├── 00_QiEOS        master doctrine / DNA / decisions / receipts / map
├── 10_QiOS_Start  front door / cockpit / access dashboard / docs surface
├── 20_QiSystem    rules / naming / schemas / lifecycle / database doctrine
├── 30_QiServer    runtime / infrastructure / deploy / monitoring
├── 40_QiCapture   ingestion / OCR / parsing / embedding / pipelines
├── 50_QiNexus     storage model / My Drive bucket doctrine
├── 60_QiApps      apps including QiLife and QiJourney
├── 70_QiConnect   connectors / integrations / APIs / workers
├── packages       reusable shared code
├── scripts        thin wrappers only
└── toolbox        local utilities and power tools

Active modules

QiAccess Start = lives under 10_QiOS_Start/QiAccess_Start
QiLife         = lives under 60_QiApps/QiLife and is the living data spine
QiJourney      = lives under 60_QiApps/QiJourney and is the interpretation / narrative branch
QiNexus        = storage model lives under 50_QiNexus, actual files live in My Drive elsewhere
QiServer       = runtime layer under 30_QiServer
QiCapture      = ingestion layer under 40_QiCapture
QiConnect      = integration layer under 70_QiConnect

4. Hard Truth Rules

Raw imports are evidence.
Canonical docs are law.
Exports are snapshots.

Do not promote raw imported docs to canon without review.

Do not delete raw imported docs.

Do not silently merge conflicting docs.

Do not duplicate the full QiNexus My Drive storage bucket tree inside this repo.

Do not invent a new folder hierarchy.

Do not treat old app-specific docs as master doctrine unless the content is promoted into 00_QiEOS or 20_QiSystem with review.

5. QiNexus Bucket Doctrine

QiNexus is the storage/workspace backbone. The actual file buckets are:

50_QiNexus/My Drive/
  00_inbox
  01_workbench
  02_timeline
  03_life
  04_people
  05_business
  06_finance
  07_legal
  08_tech
  09_assets
  10_data
  11_reference
  12_archive
  13_system

Do not create duplicate roots inside My Drive such as:

20_qinexus
30_qiarchive
40_qisystem
70_qiconnect

Those are wrong inside QiNexus storage. They belong to the QiLabs root model, not inside the My Drive bucket tree.

6. Current Repo Condition

The repo now contains a new locked-structure spine, but it also appears to contain older imported/mirrored folders such as:

01_QiDNA/
60_qiapps/
70_qiconnect/
site/

These older folders should be reviewed before moving, renaming, or deleting.

Codex should not bulldoze them.

7. Target Canonical Repo Structure

The intended canonical roots are:

_QiOS_DNA/
├── README.md
├── docs.json
├── index.mdx
├── 00_QiEOS/
│   ├── doctrine/
│   ├── decisions/
│   ├── receipts/
│   │   └── raw_imports/
│   ├── system_map/
│   ├── reconciliation/
│   └── exports/
├── 10_QiOS_Start/
│   └── QiAccess_Start/
├── 20_QiSystem/
│   ├── rules/
│   ├── schemas/
│   ├── naming/
│   ├── metadata/
│   ├── database_doctrine/
│   ├── lifecycle/
│   └── manifests/
├── 30_QiServer/
├── 40_QiCapture/
├── 50_QiNexus/
│   └── My_Drive_Model/
├── 60_QiApps/
│   ├── QiLife/
│   └── QiJourney/
├── 70_QiConnect/
├── packages/
├── scripts/
├── toolbox/
└── 09_tools/

Note: 09_tools/ is acceptable in the repo as a helper/scripts location for repo-maintenance tools, even though local QiLabs has toolbox and scripts. If desired later, it can be reconciled into toolbox or scripts, but do not move it now unless the repo convention is explicitly changed.

8. Source Material to Reconcile

Primary sources already present or expected in repo:

README.md
docs.json
index.mdx
00_QiEOS/**
10_QiOS_Start/**
20_QiSystem/**
30_QiServer/**
40_QiCapture/**
50_QiNexus/**
60_QiApps/**
70_QiConnect/**
01_QiDNA/**
60_qiapps/**
70_qiconnect/**
site/**

Source repos that informed this reconciliation:

qiallyme/_QiAccess_Start
qiallyme/qilife
qiallyme/_QiOS_DNA

Expected raw import location:

00_QiEOS/receipts/raw_imports/2026-06-09/

If raw import folders are elsewhere, do not delete them. Report where they are and recommend a move.

9. File Classification Rules

Classify each document into one of these groups:

PROMOTE_CANON
KEEP_AS_MODULE_DOC
KEEP_AS_RECEIPT
ARCHIVE_LEGACY
DUPLICATE_CONFLICT
NEEDS_REVIEW
GENERATED_EXPORT
TOOLING

Promote to canon

Promote only when a document clearly defines the whole system, naming, rules, schema, source of truth, or root structure.

Targets:

00_QiEOS/doctrine/
00_QiEOS/decisions/
00_QiEOS/system_map/
20_QiSystem/rules/
20_QiSystem/schemas/
20_QiSystem/naming/
20_QiSystem/metadata/
20_QiSystem/database_doctrine/
20_QiSystem/lifecycle/
20_QiSystem/manifests/

Keep as module doc

If the doc explains one module/app, place or summarize it under:

10_QiOS_Start/QiAccess_Start/
30_QiServer/
40_QiCapture/
50_QiNexus/My_Drive_Model/
60_QiApps/QiLife/
60_QiApps/QiJourney/
70_QiConnect/

Keep as receipt

If it is a raw import, old source snapshot, prior draft, chat-derived doc, or evidence of previous decisions, keep it under:

00_QiEOS/receipts/

Archive legacy

If it is superseded but historically useful, recommend archive location but do not delete.

Duplicate/conflict

If two docs disagree, do not merge automatically. Flag both and explain the conflict.

10. Specific Reconciliation Corrections

QiAccess Start

QiAccess Start is the front door/cockpit/access dashboard/docs surface.

It is not the whole operating system.

If any QiAccess doc says it replaces all QiOS doctrine, rewrite or flag that as outdated. Correct doctrine:

QiAccess Start replaces older dashboard/front-door framing, not QiOS itself.
QiOS DNA / QiEOS remains the master doctrine layer.

QiLife

QiLife is the living operational data spine and AI LifeDesk.

QiLife owns or models:

qibits
buckets
threads
actions
action_steps
people
transactions
obligations
knowledge_items
documents
events
links
activity_log
ai_outputs
daily_summaries

Timeline is a projection over timestamped records, not its own truth table.

QiJourney

QiJourney is interpretation, reflection, narrative, creative synthesis, and meaning-making.

QiJourney outputs are derived unless linked back to canonical records.

QiNexus

QiNexus storage buckets are not to be duplicated inside the repo as if they are root doctrine folders.

This repo may document the model under:

50_QiNexus/My_Drive_Model/

11. Codex Tasks

Task A: Generate full file inventory

Run or use:

python 09_tools/build_qios_chronicle.py

This should generate or update:

20_QiSystem/manifests/QiOS_DNA_File_Manifest.md
00_QiEOS/exports/QiOS_DNA_Chronicle.md

If the script outputs .md while Mintlify expects .mdx, do not break the docs site. Either keep .md for generated exports or add matching nav entries only when needed.

Task B: Create reconciliation matrix

Create:

00_QiEOS/reconciliation/2026-06-09_reconciliation_matrix.md

For every meaningful doc, include:

path
classification
recommended target
status
notes/conflicts

Task C: Identify outdated folder roots

Create:

00_QiEOS/reconciliation/2026-06-09_folder_drift_report.md

Include old/lowercase/non-locked folders and recommended action:

keep
move later
merge later
archive later
delete only after review

Do not delete anything in this pass.

Task D: Promote obvious canonical summaries only

Only promote documents when obvious. If uncertain, leave them in receipts and mark NEEDS_REVIEW.

Task E: Validate Mintlify docs

Check docs.json references. Ensure each referenced page exists or create a safe placeholder.

Do not point Mintlify to huge generated raw imports unless intentionally publishing them.

12. Required Deliverables

Codex should produce or update these files:

20_QiSystem/manifests/QiOS_DNA_File_Manifest.md
00_QiEOS/exports/QiOS_DNA_Chronicle.md
00_QiEOS/reconciliation/2026-06-09_reconciliation_matrix.md
00_QiEOS/reconciliation/2026-06-09_folder_drift_report.md
00_QiEOS/reconciliation/2026-06-09_codex_summary.md

Optional if useful:

00_QiEOS/reconciliation/2026-06-09_conflict_log.md
00_QiEOS/reconciliation/2026-06-09_promotion_plan.md

13. Acceptance Criteria

Reconciliation is complete for this pass when:

1. Every readable doc/config file is listed in the manifest.
2. The Chronicle export can be generated without scanning junk folders.
3. Folder drift is reported, not silently changed.
4. Mintlify navigation points only to files that exist.
5. Raw imports remain preserved.
6. Obvious canonical docs are placed in the locked QiLabs structure.
7. Unclear docs are marked NEEDS_REVIEW instead of guessed.
8. No full QiNexus My Drive bucket tree is duplicated inside _QiOS_DNA.
9. QiAccess Start is correctly treated as front door/cockpit, not master doctrine.
10. QiLife is correctly treated as data spine, not the whole OS.
11. QiJourney is correctly treated as derived interpretation/creative layer.

14. Commit Guidance

Use small commits:

Generate QiOS DNA manifest and chronicle
Add QiOS DNA reconciliation matrix
Add folder drift report
Fix Mintlify navigation references
Promote obvious canonical QiOS docs

Avoid one giant mystery commit.

15. Non-Negotiables

Do not delete raw imports.
Do not delete older folders.
Do not flatten the repo.
Do not invent new root naming.
Do not mix QiNexus storage buckets with QiLabs system roots.
Do not treat generated exports as canonical.
Do not hide conflicts.

The job is not to make the repo look clean by force.

The job is to make the repo understandable, auditable, and safe to reconcile.

QiDNA

Overview

QiDNA is the governance and documentation layer for the Qi system. It defines the mirror rule: documentation must live in the same layer as the thing it describes.

The active system model is:

QiAccess -> QiLife -> (QiSystem + QiNexus + QiCapture + QiConnect)

QiDNA names system layers, keeps their boundaries clear, and holds system-level doctrine in 01_QiDNA/QiEOS/.

Responsibilities

• Maintain the mirrored documentation structure.
• Keep system-layer names stable.
• Hold doctrine, philosophy, decisions, and system reasoning in QiEOS/.
• Prevent duplicate or conflicting source-of-truth documents.
• Record the active system model clearly and consistently.

Flows

Question
  -> identify the system layer
  -> open the matching folder
  -> read _folder.md

Runtime facts beat planning notes. Active mirrored docs beat legacy documents. QiEOS explains why, but each layer owns its operating details.

Structure

01_QiDNA/
├── _01_QiDNA.md
├── Architecture/
│   ├── _Architecture.md
│   └── Decisions/
│       └── _Decisions.md
├── Schema/
│   └── _Schema.md
├── Reconciliation/
│   └── _Reconciliation.md
└── QiEOS/
    └── _QiEOS.md

Architecture

Overview

Architecture/ records accepted QiOS boundaries and structural decisions without duplicating domain operating details.

Responsibilities

• Define cross-domain boundaries.
• Hold Architecture Decision Records in Decisions/.
• Keep accepted decisions distinct from audits and proposals.
• Link to domain documentation instead of copying it.

Flow

Architectural question -> inspect evidence -> record decision -> update domain docs

Architecture Decisions

Overview

Decisions/ contains accepted QiOS Architecture Decision Records. An ADR captures one system-wide choice and does not replace domain documentation.

Responsibilities

• State context, decision, rationale, and consequences.
• Prefer active repository and runtime evidence.
• Supersede prior decisions explicitly.

Naming

Use ADR-NNNN_short_descriptive_name.md.

ADR-0012: Data Strategy Across Supabase and QiNexus

Status

Accepted.

Context

QiDNA references an older Supabase-backed system, current QiLife documentation names SQLite as the v1 runtime database, and QiNexus is defined as durable storage and folder discipline. No Supabase migrations, local configuration, or live schema were available during the 2026-06-10 audit.

Supabase and QiNexus are not interchangeable: one can hold relational application state while the other organizes durable files and exports.

Decision

• The QiLife application database is authoritative for structured life records. The documented current implementation is SQLite.
• QiNexus is the file, export, reference, and archive layer. It is not the relational system of record.
• Supabase is a legacy source and possible integration or future database target, not a current authority. Imports require an explicit bridge and provenance.
• Replacing SQLite with Supabase requires a separate migration ADR backed by a reviewed schema, access model, backup plan, and cutover procedure.

Rationale

This matches the accepted clean-core decision and prevents folder placement from competing with database integrity or an unavailable legacy schema.

Consequences

• QiNexus stores or references blobs and exports while QiLife stores metadata and relationships.
• Supabase connectors belong to QiConnect.
• Supabase data remains non-canonical until mapped and approved.
• Schema docs must identify SQLite, legacy Supabase, or proposed future scope.

ADR-0013: Folder Documentation Model

Status

Accepted.

Context

Active domains use files such as _10_QiAccess.md, while legacy trees use _index.md, index.mdx, or no folder descriptor.

Decision

Every governed folder has one underscore-prefixed Markdown descriptor named for the folder. Numbered folders retain their number, for example _10_QiAccess.md.

The descriptor contains Overview, Responsibilities, Flows, and Structure as needed. Topic documents and ADRs may coexist, but multiple competing folder descriptors may not.

Rationale

A predictable descriptor makes each folder self-explaining and gives build and audit tools a stable discovery rule.

Consequences

• New governed folders require a descriptor when activated.
• Existing _index.md and index.mdx files require review before merge or replacement.
• Generated, imported-media, dependency, and Git-internal folders are outside this rule unless promoted into governed QiDNA.

ADR-0014: Topology Constraints

Status

Accepted.

Context

QiOS documentation is intended to remain flat, but legacy and imported trees include deeper nesting, including tracked personal media beyond four directory levels.

Decision

• Governed QiDNA paths may be at most four directories below the repository root.
• Deeper paths require documented operational necessity; categorization alone is insufficient.
• Prefer links, metadata, and indexes over repeated nesting.
• Report existing violations before changing them. Flattening, moving, or deleting requires a reviewed change.

Rationale

The limit keeps locations memorable, reduces duplicate taxonomies, and supports one generated documentation view.

Consequences

• Audits flag depth violations.
• New documentation does not deepen legacy trees.
• Imported evidence may remain unchanged until classified, but it is not a canonical topology model.

ADR-0015: Markdown to Single HTML Build

Status

Accepted.

Context

The repository has a small Node build that discovers Markdown and renders site/index.html. It also contains Mintlify navigation configuration and a Python chronicle generator. Multiple publication models can create conflicting navigation and authority.

Decision

Canonical documentation remains Markdown in its owning folders. The supported reader build is one generated static HTML file at site/index.html, produced by npm run build.

HTML, chronicles, manifests, indexes, and external publications are derived outputs and do not become canonical by being generated or deployed.

Rationale

The existing build is lightweight, searchable, portable, and introduces no additional documentation framework.

Consequences

• Stale required paths are corrected when source documents move.
• Markdown and MDX coverage must be explicit; the current HTML builder discovers .md only.
• docs.json and wiki plans remain secondary until aligned with this decision.

ADR-0016: AI as Auditor, Not Authority

Status

Accepted.

Context

QiOS uses Codex and other AI services to inspect repositories, interpret captures, draft structures, and propose changes. QiCapture and QiLife already require human review before AI output becomes official.

Decision

AI acts as auditor, analyst, and draft author. It may collect evidence, identify conflicts, generate reports, and prepare proposed changes. It may not declare runtime facts, promote drafts to doctrine, delete canonical material, or approve high-impact records without human review or an explicit trusted automation rule.

Rationale

AI improves consistency and scale but can be incomplete or wrong. QiDNA must remain traceable to repository evidence, runtime verification, accepted decisions, and accountable approval.

Consequences

• AI reports identify unknowns and unavailable evidence.
• Accepted ADRs and merged source documents, not chat output, carry authority.
• Destructive or topology-changing recommendations require explicit review.
• Runtime facts override AI inference and stale planning notes.

QiEOS

Overview

QiEOS is the governing doctrine for the Qi system.

Core rules:

• Flat over nested when a simpler structure answers the question.
• Linked over duplicated.
• Documented over remembered.
• Modular over massive.
• Runtime facts beat assumptions.
• Derived layers do not become truth by themselves.

Responsibilities

• Hold doctrine, philosophy, decisions, and system reasoning.
• Keep system layer names fixed.
• Explain why the mirror structure exists.
• Resolve conflicts by aligning old material to the active system model.

Flows

Doctrine or decision question
  -> 01_QiDNA/QiEOS/_folder.md
  -> apply reasoning to the matching system-layer folder

QiEOS explains why. Each system folder documents what it owns and how it operates.

Structure

System layer names are fixed: QiDNA, QiAccess, QiSystem, QiServer, QiCapture, QiNexus, QiApp QiLife, and QiConnect.

Reconciliation

Overview

Reconciliation/ compares QiDNA doctrine, repository structure, implementation documentation, and verified runtime facts.

Responsibilities

• Record inspected and unavailable evidence.
• Separate facts from proposals.
• Classify recommendations as ADD, MERGE, UPDATE, or DELETE.
• Preserve unresolved conflicts pending an accepted decision.

QiDNA Blueprint Readiness and Decision Gate

Purpose

This document states whether QiDNA is ready to govern database and UI implementation and identifies the decisions required before that work continues.

Assessment date: 2026-06-10.

Current Position

QiDNA has a sound governance foundation, but it is not yet a contradiction-free or implementation-complete master blueprint.

The repository is synchronized, the active 01-70 domains are documented, the architecture ADRs are in place, and the single-page site builds successfully. Structural reconciliation and implementation specifications remain incomplete.

Established Foundations

• Eight primary domains define the current system boundary.
• ADRs define data strategy, folder documentation, topology, build strategy, and the AI auditor role.
• The reconciliation report records naming, ownership, topology, and persistence conflicts.
• SQLite, QiNexus, and legacy Supabase have separate intended responsibilities.
• The generated site provides a searchable single-page documentation reader.

Blocking Issues

1. Competing Root Models

The repository still presents two architectures as if both are current:

Current: 01_QiDNA, 10_QiAccess, 60_QiApp_QiLife
Legacy:  00_QiEOS, 10_QiOS_Start, 60_QiApps

README.md, docs.json, doctrine, manifests, and module documents do not yet use one canonical vocabulary.

2. Incomplete Site Coverage

The current Node builder renders .md files but omits .mdx files. Fourteen MDX documents are absent from the site, including the historical master map, source-of-truth rules, QiLife data spine, and several module pages.

The site also renders current and legacy Markdown together without visible status labels.

3. Incomplete Database Blueprint

The entity catalog exists, but the following are not yet canonical and complete:

• field definitions and types
• primary and foreign keys
• relationship cardinality
• status values and transition rules
• uniqueness and validation constraints
• indexes and query requirements
• ownership and provenance rules
• retention, archive, and deletion behavior
• migration and backup rules
• authorization and sensitive-data boundaries

The actual QiLife SQLite schema and legacy Supabase schema were not available for comparison.

4. Incomplete UI Blueprint

Module flows exist, but the following are not yet unified:

• application route map
• screen and view inventory
• component ownership
• navigation hierarchy
• loading, empty, error, and offline states
• create, review, approve, edit, archive, and delete flows
• entity-to-screen and API-to-screen mappings
• permissions and visibility rules
• accessibility and responsive behavior requirements
• acceptance criteria for each workflow

Readiness Decision

Broad database and UI implementation should not begin from the current documentation alone.

The required sequence is:

1. Select and document the canonical root vocabulary.
2. Label all competing documents as Active, Legacy, Proposed, Generated, or Evidence.
3. Consolidate active domain documentation without deleting historical evidence.
4. Make the generated site include all supported canonical formats and display document status.
5. Complete and verify the database blueprint against the actual implementation schema.
6. Complete the route, screen, workflow, and UI-to-entity blueprint.
7. Implement database changes, then API contracts, then UI behavior.

Decision Package Required From Cody

Review the documents listed below and provide explicit decisions for each question.

Canonical Structure

Review:

• 01_QiDNA/_01_QiDNA.md
• 01_QiDNA/QiEOS/_QiEOS.md
• 00_QiEOS/system_map/QiOS_Master_Map.mdx
• 00_QiEOS/doctrine/QiOS_Core_Doctrine.mdx
• README.md

Decision:

• Is the canonical root model the current 01_QiDNA through 70_QiConnect structure?
• Is QiEOS a doctrine section inside QiDNA rather than a separate top-level root?
• Is the canonical front-door name QiAccess rather than QiOS Start or QiAccess Start?
• Is the canonical application name and root QiApp QiLife / 60_QiApp_QiLife?

Data Authority

Review:

• 01_QiDNA/Architecture/Decisions/ADR-0012_data_strategy.md
• 20_QiSystem/schemas/QiLife_Data_Spine.mdx
• 90_decisions/0006_clean_core_with_legacy_bridge.md
• 70_deployment/00_local_dev.md

Decision:

• Confirm SQLite as the current QiLife structured-data authority.
• Confirm QiNexus as file, export, reference, and archive storage rather than a database.
• Confirm Supabase as legacy/import or future integration only.
• Provide or identify the actual QiLife schema repository and database path.

Product Scope

Review:

• 60_QiApp_QiLife/_60_QiApp_QiLife.md
• 90_decisions/0001_personal_lifedesk_model.md
• 90_decisions/0002_qibit_as_atomic_unit.md
• 90_decisions/0003_timeline_as_spine.md
• 90_decisions/0009_agent_first_copilot_cockpit.md
• 90_decisions/0010_spaces_for_scoped_shared_access.md

Decision:

• Confirm which entities and modules are required for v1.
• Confirm whether Spaces and shared access are v1 or later.
• Confirm whether AI is central to v1 or staged after manual workflows.

UI Direction

Review:

• 10_QiAccess/_10_QiAccess.md
• 60_QiApp_QiLife/_60_QiApp_QiLife.md
• 50_modules/*/overview.md
• 50_modules/*/ui_flow.md
• 60_ai_layer/02_ai_review_workflow.md

Decision:

• Confirm the primary navigation and first screens to implement.
• Confirm whether QiAccess and QiLife are separate applications or one shell with embedded modules.
• Confirm the minimum capture, inbox, timeline, action, and review workflows for v1.

Exit Criteria

Database and UI work may proceed when:

• one root vocabulary is accepted
• contradictory documents are labeled or reconciled
• the actual database schema is available and mapped to the entity catalog
• v1 entities, statuses, and relationships are approved
• v1 routes, screens, and workflows are approved
• the generated site contains the complete active blueprint without presenting legacy material as current authority

Readiness Estimate

• Governance and architecture foundation: approximately 70 percent.
• Implementation-level database and UI specification: approximately 40-50 percent.
• Current status: documentation consolidation and decision review required before implementation expansion.

QiDNA and Implementation Reconciliation

Scope

Audit date: 2026-06-10.

Inspected evidence included all tracked paths; active 01-70 descriptors; doctrine, schema summaries, decisions, module docs, workflows, deployment notes, build scripts, and project receipts. Binary personal-media imports were inventoried by path but were not treated as architecture documents.

No Supabase migrations, supabase/config.toml, SQL schema, or connected Supabase project was available. No claim about a live Supabase schema is made.

Extracted System Model

Domains and Boundaries

Entities

Documented QiLife entities are qibits, buckets, threads, actions, action_steps, people, transactions, obligations, knowledge_items, documents, events, links, activity_log, ai_outputs, and daily_summaries.

Capture entities are raw capture, ingestion item, extracted content, AI draft, review decision, accepted QiLife record, and activity entry.

Infrastructure entities include host, stack, service, route, access class, backup, health result, audit, and generated report.

Relationships

• Raw capture becomes an ingestion item and may produce an AI draft.
• An approved draft creates or updates a QiLife entity.
• links preserves provenance between QiBits and derived records.
• Threads group QiBits, actions, documents, transactions, obligations, and people.
• Timeline projects timestamped entities; it is not a canonical table.
• QiLife metadata links to files governed by QiNexus.
• QiConnect routes external requests to protected QiServer services.

Flows

Capture -> Extract -> Draft -> Review -> Approve/Edit/Reject -> QiLife -> Timeline
QiAccess -> tool or service -> QiServer route -> application
Canonical Markdown -> npm run build -> site/index.html

Findings and Recommendations

Suggested Structural Updates

These are proposals, not executed moves or deletions.

1. MERGE 10_QiOS_Start/QiAccess_Start and reviewed 60_qiapps/qiaccess_start material into 10_QiAccess.
2. MERGE 60_QiApps/QiLife, 60_ai_layer, relevant 50_modules, and QiLife deployment docs into 60_QiApp_QiLife.
3. MERGE 50_qiserver/qiserver_runbook.md into 30_QiServer.
4. MERGE 70_qiconnect/06_workflows into 70_QiConnect.
5. MERGE reviewed 20_qinexus content into 50_QiNexus.
6. UPDATE 00_QiEOS doctrine and docs.json to identify the current model or label them legacy.
7. DELETE empty placeholders and redundant legacy roots only after reviewed merges.

Unknowns

• The live QiLife repository and its actual SQLite migrations were not present.
• The legacy Supabase schema and project configuration were unavailable.
• Runtime components were described by receipts but not re-verified in this repository-only audit.
• The intended disposition of the tracked personal-media import is unstated.

Schema

Overview

Schema/ describes QiOS domains, entities, relationships, flows, and boundaries while distinguishing intent from verified implementation.

Responsibilities

• Define shared system concepts.
• Link detailed schemas from their owning domain.
• Mark proposed structures as proposed.
• Avoid duplicating migrations or runtime configuration.

Current Model

QiAccess -> QiLife -> (QiSystem + QiNexus + QiCapture + QiConnect)
                         |
                      QiServer

QiAccess

Overview

QiAccess is the portal and navigation shell for the system. It is the daily entry point for opening tools, seeing what needs attention, capturing quickly, and reaching system services.

Responsibilities

• Provide the main portal and dashboard.
• Open real tools and services quickly.
• Present the seven-root navigation contract.
• Surface Capture as a fast path.
• Point Knowledge to canonical docs and references.
• Show System visibility without becoming the system layer itself.

Flows

Open QiAccess
  -> see Home for attention items
  -> use Start to open tools
  -> use Capture for immediate input
  -> use Knowledge for references
  -> use System for runtime visibility

Structure

QiAccess active navigation has seven roots: Home, Start, Capture, Knowledge, Memory, Insights, and System. System subroutes stay nested under System.

80 Tech

Placement file created from blueprint_master_map-mindmap.md. Use this folder for technical systems, devices, and software operations.

90 Assets

Placement file created from blueprint_master_map-mindmap.md. Use this folder for durable owned assets and related records.

QiSystem

Overview

QiSystem is the operational integrity layer. It tracks evidence that the system is running correctly and keeps generated operational material separate from product, portal, and doctrine docs.

Responsibilities

• Logs and operational records.
• Audits and validation outputs.
• Backup and restore references.
• Health checks and verification results.
• Generated reports.
• Generated indexes and inventories.
• Maintenance notes and cleanup tasks.

Flows

Runtime or service check
  -> health result
  -> audit or generated report
  -> maintenance action if needed
  -> retained QiSystem record

Structure

QiSystem may contain physical subfolders for real operational records when needed. Each subfolder must contain its own _folder.md when created.

QiLife Governance-First Repository Audit

Date: 2026-06-08

Scope: Read-only audit of the current QiOS DNA repository, its Git history, QiLife planning material, and available persistence evidence. No application or database implementation was performed.

A. Current Repo State

• Workspace: /home/qiadmin/qi_workspace/_QiOS_DNA
• Remote: https://github.com/qiallyme/_QiOS_DNA.git
• Branch: main, aligned with origin/main at audit time.
• Working tree: clean at audit time.
• Latest commit: 0d58afd (Fix folder doc naming to _FolderName.md standard), dated 2026-06-05.
• The current repository is a QiOS documentation shell with a static HTML viewer. It is not a QiLife application codebase.
• Current top-level system layers are 01_QiDNA, 10_QiAccess, 20_QiSystem, 30_QiServer, 40_QiCapture, 50_QiNexus, 60_QiApp_QiLife, and 70_QiConnect.

B. Existing Implemented Pieces

• Governance and system-boundary documentation exists for the active QiOS layers.
• site/ contains a static single-page documentation viewer.
• QiLife has a documented conceptual lifecycle from capture through retrieval.
• The active QiLife document names proposed v1 entities: qibits, buckets, threads, actions, action_steps, people, transactions, obligations, knowledge_items, documents, events, links, activity_log, ai_outputs, and daily_summaries.
• QiCapture documents intake, interpretation review, and handoff to QiLife.
• QiNexus documents durable storage buckets and folder alignment.
• Historical Git revisions contain detailed planning for the QiBit lifecycle, modules, data fields, seed data, build phases, and a local-first database strategy. Commit ed32390 removed that planning corpus from the active tree.
• No current or historical matches were found for KeyLife, HumanOps, Communication Playbook, or Relationship Triage in the inspected repository revisions.

C. Existing Database Setup

• Requested database path: C:\QiLabs\60_QiApps_qilife\data\db\qilife.sqlite.
• The database was not found at that path or at the corresponding mounted path /mnt/c/QiLabs/60_QiApps_qilife/data/db/qilife.sqlite.
• No qilife.sqlite, qilife.sqlite3, or qilife.db was found under the accessible /home/qiadmin or /srv/qios trees.
• Because the database is missing, it could not be opened and no tables could be inspected.
• The current repository contains no SQLite database, SQL schema, migrations, ORM configuration, backend, API, or database connection configuration.
• The static viewer does not use a backend or persistence layer.
• Historical planning prescribed SQLite for QiLife v1, migrations from day one, and a later migration path to Postgres. One historical document used a different location: C:\QiLifeData\db\qilife.sqlite.
• Historical seed records and table definitions are documentation only, not executable database artifacts.

D. Missing Database Foundation

• No active canonical persistence decision.
• No executable schema, constraints, indexes, or foreign keys.
• No migration framework or initial migration.
• No database initialization or health verification.
• No canonical database path ownership.
• No backend data-access layer.
• No transaction or concurrency policy.
• No backup, restore, export, or migration verification workflow.
• No persistence tests.

The active QiLife documentation names tables but does not define an implementation-ready schema. The project is not currently using persistent, mock, or client-side application data because no current application implementation exists.

E. Unfinished or Suspicious Tasks

• docs.json references _folder pages, but the physical documents were renamed to _FolderName.md files.
• The README and layer documentation still describe _folder.md as the required convention, while no _folder.md files remain.
• site/script.js embeds copies of the Markdown content instead of loading the physical documents, allowing the viewer and source documents to drift.
• The viewer displays paths ending in /_folder.md, although those paths no longer exist.
• fix_folder_names.sh remains after the repository-wide rename.
• Detailed schema, module, roadmap, seed, and migration planning was removed from the active tree without equivalent active replacements.

F. Conflicts and Duplicates

• Documentation naming conflict: _folder.md governance versus _FolderName.md files.
• Navigation conflict: docs.json points to missing page names.
• Source duplication: Markdown documents and embedded copies in site/script.js.
• Persistence conflict: historical QiLife plans say SQLite first and Postgres later, while other historical QiOS material alternately describes Supabase/Postgres as canonical, conditional, or legacy.
• Database path conflict: the requested C:\QiLabs\60_QiApps_qilife\data\db\qilife.sqlite differs from the historically documented C:\QiLifeData\db\qilife.sqlite.
• Product naming conflict remains unresolved because no KeyLife definition exists in the inspected repository.

G. Recommended Next Step

Do not begin feature implementation until a governance decision record establishes:

1. The canonical product name and repository ownership.
2. SQLite or Postgres authority for v1.
3. The canonical database location.
4. Which removed historical schema material remains valid.
5. Migration ownership and versioning.
6. One documentation filename convention and one documentation source of truth.

After approval, the first implementation should be a migration-backed persistence foundation with schema verification tests, before UI or module development.

50 Context Packs

Placement file created from blueprint_master_map-mindmap.md.

QiServer

Overview

QiServer is the protected runtime host for internal services. It contains live Docker Compose stacks, system services, private access routes, public restricted routes, and runtime configuration paths.

Verified runtime facts win over repo planning notes.

Responsibilities

• Host protected runtime services.
• Keep runtime stack paths and service facts clear.
• Separate public restricted access from private-only access.
• Run Docker Compose stacks and systemd services.
• Verify local, tailnet, and public routes after changes.

Flows

Inspect qiserver
  -> confirm repo, branch, remote, stack, ports, and working tree
  -> pull only from the confirmed repo
  -> back up runtime config before overwriting
  -> deploy or restart only the needed stack
  -> verify routes

Structure

Known runtime paths include /srv/qios/stacks/_qiaccess_start, /srv/qios/stacks/_qiaccess_start/docker-compose.yml, and /srv/qios/apps/_QiAccess_Start/qiaccess/config.

QiCapture

Overview

QiCapture is the intake, ingestion, review, and approval layer. It protects raw input while turning it into usable QiLife records.

Raw capture is sacred. AI interpretation is a draft until approved or trusted by explicit rules.

Responsibilities

• Fast intake of raw thoughts, files, notes, messages, and documents.
• Preserve original capture text or source files.
• Create ingestion items.
• Run extraction or inspection.
• Produce draft interpretations.
• Support approve, edit, or reject review actions.
• Hand official records to QiLife.

Flows

Raw capture
  -> ingestion item
  -> extraction
  -> AI draft
  -> review
  -> approve, edit, or reject
  -> QiBit, Action, or Thread

Structure

QiCapture records distinguish raw capture, ingestion item, extracted text or metadata, AI draft, review decision, official QiLife object, and timeline/activity log entry.

Calendar: UI Flow

1. Grid Views: Cody switches between Day, Week, and Month layouts.
2. Scheduled Feed: Displays scheduled Actions and Events side-by-side with daily log milestones.
3. Drag & Drop: Cody moves an event block to reschedule the corresponding Action.

Capture Module

The capture module is responsible for the intake of raw data.

Raw capture is sacred. This module handles receiving input from the user (text, voice, files) and saving it as an ingestion item without trying to interpret it too heavily before it hits the DB.

Documents: AI Behaviors

• Metadata Extraction: AI parses text descriptions to suggest tags, buckets, and people relationships.
• Receipt Parsing: Future modules will utilize OCR to extract transaction dates, vendors, and line items.

Documents: Context Dock Integration

When viewing a Document detail card, the Context Dock shows:

• The parent QiBit that originally captured the file.
• The Transaction or Obligation this file verifies.
• Related People or companies associated with the document.

Documents: Data Dependencies

• Reads/Writes: Database records written to the documents table.
• Links: Heavily dependent on the links table to establish relationships with qibits, transactions, obligations, and people.

Documents: Overview

The Documents module acts as a metadata archive for external physical assets, scans, receipts, and files. In the Personal LifeDesk model, a Document represents evidence supporting tickets or transactions, ensuring everything has auditability.

Documents: UI Flow

1. Document Grid: Cody browses uploaded receipts, scans, and PDFs categorized by Buckets.
2. Details Panel: Shows document title, file path, upload timestamp, and links.
3. Link Wizard: Cody clicks "Link Document" to attach it to an active Thread, Transaction, or Action.

Inbox: AI Behaviors

• Triage Recommendation: Backend calls interpret_qibit and extract_related_entities to pre-fill the triage forms.
• Confirmation Loop: In Inbox, Cody clicks "Approve Suggestions" to commit the AI-inferred structures.

Inbox: Context Dock Integration

During triage, the Context Dock retrieves:

• Similar historical QiBits (to prevent duplicate logs).
• Potential matching Threads or People based on words in the raw capture.
• AI suggestion confidence metrics.

Inbox: Data Dependencies

• Reads/Writes: Reads and updates the qibits table.
• Writes: Creates records in actions, obligations, or threads when triage outcomes are committed.

Inbox: Overview

The Inbox module is the triage staging area for raw life data. In the Personal LifeDesk model, the Inbox matches the 00 Inbox bucket, holding captured QiBits until Cody reviews, interprets, and routes them.

Inbox: UI Flow

1. Inbox Feed: Cody views cards for unprocessed QiBits (status = 'new').
2. Triage Wizard: Clicking a card opens a split panel showing raw text on the left and input forms on the right.
3. Bulk Action: Cody can select multiple items to assign to a single Bucket, or mark them as reference/ignored in bulk.

Ingestion Module

The ingestion module takes raw capture items and prepares them for the agent.

This includes extracting text from files, deduplication checking (dup-allergic), and generating structured extraction requests for the AI.

Knowledge: AI Behaviors

• Semantic Retrieval: AI calls find_relevant_knowledge to automatically pull relevant articles based on active contexts.
• Summarization: AI summarizes lengthy knowledge documents for quick-display in sidebar widgets.

Knowledge: Context Dock Integration

In full reading mode, the Context Dock is collapsed. In work mode, knowledge articles are displayed inside the Context Dock next to active Actions.

Knowledge: Data Dependencies

• Reads/Writes: Writes to knowledge_items table.
• Sync: Integrates with external repository syncer tool to index local files.

Knowledge: Overview

The Knowledge module holds durable reference manuals, operating rules, templates, and decisions. In the Personal LifeDesk model, knowledge is stored directly in the database (knowledge_items) to remain tightly integrated with operations.

Knowledge: UI Flow

1. Knowledge Home: Cody searches knowledge articles or browses them by Bucket hierarchy (e.g. 110 Reference).
2. Markdown Reader/Editor: Cody views formatted markdown guides or edits the text directly in a simple textarea.
3. Usage Tracker: Interface displays a list of operational objects (actions, threads) currently linking to this page.

Money: AI Behaviors

• Text Extraction: AI parses sentences (e.g. "Paid gas station $65") using extract_transaction_from_text to populate forms.
• Loan Detection: AI detects debt markers in text using extract_obligation_from_text.

Money: Context Dock Integration

When viewing money ledgers, the Context Dock displays:

• Summary statistics (net cash flow, total outstanding loans).
• Evidence documents (receipt uploads, invoices) linked to transactions.

Money: Data Dependencies

• Reads/Writes: Writes to transactions and obligations tables.
• Foreign Keys: Connects to people (via label or link) and threads (via thread_id).

Money: Overview

The Money module manages financial ledger entries. In the Personal LifeDesk model, it tracks cash flow (transactions) and outstanding bilateral debts (obligations), providing Cody with a clear ledger of balances.

Money: UI Flow

1. Ledger Table: Cody reviews transactions filtered by category or bucket.
2. Obligations Hub: Cody views debt balances ("Who owes me", "Who I owe") categorized by person.
3. Log & Settle: Cody logs new entries or records a payment transaction to settle an open obligation.

People: AI Behaviors

• Entity Extraction: AI runs extract_related_entities on raw inputs to automatically link contacts.
• Interaction Logging: AI suggests logging communication events when parsing chat logs.

People: Context Dock Integration

When visiting a Person profile, the Context Dock shows:

• Active Threads involving this person.
• Unresolved Obligations (e.g. loans, documents pending response).
• Recent timeline events touching this contact.

People: Data Dependencies

• Reads/Writes: Writes to people table.
• Links: Connected via the links table to actions (who is assigned/involved) and obligations (who owes money).

People: Overview

The People module provides contact context and tracking for external entities. In the Personal LifeDesk model, people are treated as requesters, vendors, or collaborators, avoiding complex sales CRM pipelines in favor of relationship histories.

People: UI Flow

1. Directory: Cody browses a directory of contacts, companies, courts, and agencies.
2. Profile Page: Displays contact info, custom relationship notes, and a linked timeline log.
3. Log Touches: Cody logs manual interaction milestones (e.g. "Called agency representative").

QiBits: AI Behaviors

• Core Triage Engine: Drives interpret_qibit and extract_related_entities calls.
• Reflection Prompts: Generates cognitive evaluations from the QiBit context.

QiBits: Context Dock Integration

When viewing a specific QiBit, the Context Dock exposes:

• Provenance trails (all objects spawned from this QiBit).
• AI reasoning output logs (ai_outputs).
• Associated reflection prompts.

QiBits: Data Dependencies

• Reads/Writes: Primary write targets are the qibits table.
• Links: Serves as the origin parent node for almost all links in the links table.

QiBits: Overview

The QiBits module handles the atomic lifecycle cards. In the Personal LifeDesk model, a QiBit is the entry ticket representing one captured unit of life data before or after it is parsed into the system.

QiBits: UI Flow

1. Quick Capture Bar: Cody captures thoughts in the global top/bottom input bar.
2. QiBit Detail Drawer: Displays raw text, parsed summaries, and links to target actions.
3. Triage Status Check: Shows current lifecycle badge (new, triaged, resolved, closed).

Review Module

The review module handles the human-in-the-loop approval of AI drafts.

High-risk areas like money, legal, medical, deletion, and external messaging require human review. This module logs approval, edits, and rejections of drafts before they become official records.

Spaces Module

The spaces module handles scoped shared access.

It enforces visibility rules (private, space_visible, restricted, archived) and manages members and roles (owner, contributor, viewer, guest) within spaces like Mom Care and Household.

Storage Module

The storage module manages the app's local data footprint.

It handles paths for the SQLite DB, file vault, and exports, enforcing the boundary between structured truth (DB) and raw files (blob store).

Threads: AI Behaviors

• Thread Summarization: AI runs summarize_thread to aggregate updates and compile status bullets.
• Next Action Suggestion: AI recommends the logical next task to unblock the thread.

Threads: Context Dock Integration

The Context Dock is heavily utilized on Thread detail pages. It renders:

• An AI Summary of the thread status.
• All linked Knowledge Items (e.g. guidelines for that project).
• Linked Documents and financial spreadsheets.

Threads: Data Dependencies

• Reads/Writes: Writes to the threads table.
• Foreign Keys: Actions, QiBits, and Transactions possess a nullable thread_id pointing directly to this table.

Threads: Overview

The Threads module groups related operational cards into case files, storylines, or projects. In the Personal LifeDesk model, Threads represent ongoing situations (e.g., Surplus Check Recovery) that aggregate actions, people, and documents.

Threads: UI Flow

1. Thread Index: Cody views a list of open, active, waiting_on, resolved, or closed threads.
2. Thread Ledger: The thread detail shows related QiBits, actions, transactions, obligations, documents, and recent timeline projections for the situation.
3. Status Control: Cody updates the thread state using canonical statuses, for example active to waiting_on, or waiting_on to resolved.

Timeline: AI Behaviors

• Summary Service: AI runs summarize_day to generate structured bullet summaries of the timeline events.
• Loop Scanning: AI monitors the timeline to flag outstanding open loops in the Context Dock.

Timeline: Context Dock Integration

When focused on a specific day or week in the Timeline, the Context Dock displays:

• A synthesized Daily Summary list.
• Reflection Prompts for that day.
• Key statistics (money spent, steps completed).

Timeline: Data Dependencies

• Reads:
  • qibits
  • actions
  • transactions
  • events
  • daily_summaries
• Projection rules:
  • QiBits by COALESCE(happened_at, captured_at, created_at)
  • Actions by completed_at, else scheduled_for, else created_at
  • Transactions by date
  • Events by start_time
  • Daily summaries by date
• Writes: none directly; Timeline is a read model built from other tables.

Timeline: Overview

The Timeline module serves as the chronological spine of QiLife. It aligns with the Personal LifeDesk model by aggregating actions, transactions, and logs into a single time-based feed representing what happened.

Timeline: UI Flow

1. Chronological Feed: Cody scrolls an infinite feed of events, note/reflection-type QiBits, transactions, daily summaries, and completed tasks.
2. Filter Controls: Selectors filter the feed by bucket, thread, person, type, or importance.
3. Day Breakdown: Clicking a day header collapses or expands that day's records.

QiNexus

Overview

QiNexus is the storage backbone and folder discipline layer. It provides the durable workspace for life, projects, knowledge, data, reference material, and archive records.

Responsibilities

• Folder discipline.
• Durable storage categories.
• Bucket alignment for QiLife.
• Archive placement.
• Reference material placement.
• Data exports and structured datasets.

Flows

Item needs storage
  -> identify bucket/domain
  -> place in matching QiNexus location
  -> link from QiLife record when applicable
  -> archive only when inactive or historical

Structure

Canonical buckets: 00 Inbox, 10 Workbench, 20 Timeline, 30 Life, 40 People, 50 Business, 60 Finance, 70 Legal, 80 Tech, 90 Assets, 100 Data, 110 Reference, 900 Archive, and 990 System.

QiServer Runbook

This document details the operational triage, monitoring, and recovery runbooks for QiServer, the central host of the QiAccess ecosystem.

1. Verified Facts

• Host System: A local server node at 100.121.111.106 running on the Tailnet.
• Port Bindings:
  • SSH: 22
  • Cockpit Administration: 9090
  • Open WebUI: 9446
  • Paperless-ngx Serve Proxy: 9447
  • Wiki.js Serve Proxy: 9448
  • Portainer Container Admin: 9449
  • Firefly III: 6877 (HTTP)
  • Firefly Importer: 6878 (HTTP)
  • SolidTime: 9453 (HTTPS)
  • Neo4j: 7474 (HTTP)
• Repo-side Canonical Homepage Config Source: c:\QiLabs\_QiAccess_Start\qiaccess\config\
• Docker Compose Stack Path: /srv/qios/stacks/ or /srv/qios/stacks/_qiaccess_start/ on the server.
• Deployment Boundary: Local repo edits are not live until Server Codex pulls the repo and syncs the config files into /srv/qios/stacks/_qiaccess_start/config/.

2. Target Hierarchy

• This file is situated in: docs/50_qiserver/qiserver_runbook.md.
• Works in conjunction with system status monitoring pages and Uptime Kuma alerts.

3. Actual Runtime / Storage Locations

• Server Host: Physical system or VM managed via Tailscale.
• Config Backup Destination: Synced to docs/10_qicore/10_governance/60_registry/ and backup drives.
• Compose Files: Kept in local repository stack folders on the host machine.
• Homepage Config Sync Target: /srv/qios/stacks/_qiaccess_start/config/

4. Unknowns

• Exact root partition structure and disk utilization alert thresholds on the host.
• The credentials required to access the Portainer dashboard stack if credentials lose sync.

5. Needs Cody Confirmation

• How are system credentials backed up for offline emergency access?
• Is there a hardware-level IP KVM (like Pi-KVM) connected to the host for origin down triage?

6. Wiki.js-Ready Summary

QiServer Runbook provides step-by-step procedures for origin-down recovery, SSH diagnostic routines, Docker stack restarts, and port mapping checks. It serves as the authoritative operational manual for maintaining local AI model inference (Ollama), document intake (Paperless), and database runtimes.

7. Implementation Notes

• Emergency SSH:

  ssh qiadmin@qiserver-1.cerberus-sirius.ts.net
  

• Repo-to-Server Sync Rule:
  • Update repo-side canonical config in c:\QiLabs\_QiAccess_Start\qiaccess\config\
  • Push to GitHub from the local PC repo
  • Have Server Codex pull the repo on qiserver
  • Sync the config files into /srv/qios/stacks/_qiaccess_start/config/
  • Only then restart or reload the private Homepage stack if needed
• Service Recovery Steps:
  1. Ping the host over Tailscale: ping 100.121.111.106.
  2. Access the Cockpit console on https://100.121.111.106:9090.
  3. Inspect container states: docker ps or log in to Portainer on port 9449.
  4. Restart compose stacks:

     cd /srv/qios/stacks/_qiaccess_start
     docker compose down && docker compose up -d
     

QiLife AI Layer Blueprint

Principle

AI should be directly connected to the life ledger, not floating beside it as a detached chatbot.

AI should read, summarize, classify, retrieve, and eventually help update:

• QiBits
• timeline projections
• buckets
• threads
• actions
• people
• transactions
• obligations
• documents
• knowledge items
• note-type QiBits
• reflection-type QiBits

V1 AI Behavior

V1 may use mock responses, but the service boundaries should exist from the start.

AI Service Functions

interpret_qibit
extract_related_entities
suggest_actions
generate_action_steps
find_relevant_knowledge
suggest_future_slot
summarize_day
summarize_thread
extract_transaction_from_text
extract_obligation_from_text
answer_life_query
generate_reflection_prompt

Human Review Rule

AI should suggest. Cody approves.

For v1, AI should not silently create or modify important records without a review step.

Ask QiLife Example Questions

• What happened today?
• What matters right now?
• What am I waiting on?
• Who owes me money?
• What tasks involve Zai?
• What legal items are open?
• What is the next action on the surplus check?
• What did I spend on gas this week?
• Turn this rant into QiBits, actions, and note-type QiBits.
• What is real, what is noise, and what do I do next?

AI Response Shape

answer
supporting_records
suggested_actions
related_people
related_threads
confidence
save_options

Save Options

AI output should be savable as:

• QiBit
• action
• knowledge item
• thread summary
• reflection
• daily summary draft

QiLife AI Service Contracts

This document defines the v1 AI service interfaces. The contracts must align with the canonical SQLite schema so that mocked AI behavior can graduate cleanly into live AI later.

Contract Rules

• Use ULID strings for record identifiers.
• Monetary values returned for structured writes should include amount_cents.
• AI suggestions write to ai_outputs first and only reach primary tables after approval.
• AI can suggest note/reflection content as QiBit payloads; there are no dedicated notes or reflections tables in v1.

1. QiBit Interpretation

interpret_qibit

Request:

{
  "raw_capture": "string (max 1000 chars)",
  "captured_at": "datetime (ISO 8601)"
}

Response:

{
  "title": "string",
  "summary": "string",
  "meaning": "string",
  "suggested_qibit_type": "string",
  "suggested_bucket_code": "string",
  "importance": "string",
  "priority": "string",
  "emotional_load": "string",
  "action_required": true,
  "suggested_action": "string | null",
  "suggested_future_slot": "string (today | this_week | scheduled | waiting_on | someday | knowledge_base)"
}

extract_related_entities

Request:

{
  "qibit_id": "string (ULID)",
  "content": "string"
}

Response:

{
  "people": [
    {
      "display_name": "string",
      "relationship_hint": "string | null"
    }
  ],
  "organizations": ["string"],
  "financials": [
    {
      "amount_cents": 4000,
      "currency": "USD",
      "type": "obligation"
    }
  ],
  "dates": [
    {
      "extracted_date": "2026-05-29",
      "label": "occurred_date"
    }
  ]
}

2. Action Generation

generate_action_steps

Request:

{
  "action_id": "string (ULID)",
  "action_title": "string",
  "action_description": "string"
}

Response:

{
  "steps": [
    {
      "title": "string",
      "description": "string | null",
      "sort_order": 1
    }
  ]
}

3. Financial Extraction

extract_transaction_from_text

Response:

{
  "date": "2026-05-29",
  "amount_cents": 6523,
  "currency": "USD",
  "direction": "out",
  "from_label": "Cody",
  "to_label": "Shell Gas Station",
  "category": "gas",
  "notes": "string | null"
}

extract_obligation_from_text

Response:

{
  "owed_by_label": "Zai",
  "owed_to_label": "Cody",
  "obligation_type": "money",
  "amount_cents": 4000,
  "currency": "USD",
  "reason": "Gas payment share for Lyft driving run",
  "due_date": "2026-05-30 | null"
}

4. Ask QiLife

answer_life_query

Request:

{
  "query": "string",
  "active_bucket_code": "string | null",
  "active_thread_id": "string | null"
}

Response:

{
  "answer": "string (Markdown)",
  "confidence": 0.86,
  "supporting_records": [
    {
      "record_type": "obligations",
      "record_id": "01JWNZ4M5N6P7Q8R9S0T1U2V3A",
      "relevance_reason": "Open money obligation for Zai"
    }
  ],
  "suggested_actions": ["Send a follow-up message to Zai"],
  "related_people_ids": ["01JWNX2D3Q4A5B6C7D8E9F0G1J"],
  "related_thread_ids": ["01JWNX8F6R7S8T9U0V1W2X3Y4A"]
}

Saving an answer can create:

• a QiBit of type note
• a QiBit of type reflection
• an action
• a knowledge item

It should not create a record in a non-existent notes table.

5. Reflection Prompt

generate_reflection_prompt

Request:

{
  "date": "2026-05-29",
  "completed_actions_count": 2,
  "open_loops_count": 3,
  "daily_summary": "string"
}

Response:

{
  "reflection_prompt": "string",
  "cognitive_load_estimate": "high"
}

QiLife AI Review Workflow

To prevent AI hallucinations, model drift, or unintended edits from corrupting Cody's personal ledger, QiLife operates on a strict Human-in-the-Loop (HITL) doctrine. The AI proposes; Cody approves or edits.

1. Core Principles

1. No Silent Creation: The AI service never directly inserts or updates records in primary tables (actions, obligations, transactions, people, threads) without user intervention.
2. Draft / AI Output Staging: All AI inferences are written to the ai_outputs table first. They are displayed in the UI as editable suggestions.
3. Explicit Acceptance: A suggestion only moves to the primary tables when Cody clicks Accept (which marks ai_outputs.accepted = true and performs the writes) or modifies the values and clicks Save.
4. Provenance Tracking: Created items retain a link to their originating qibit_id and ai_output_id via the links table.

2. The Triage Review Pipeline

The primary review pipeline happens in the Inbox during the Triage phase of a QiBit.

  [Raw Capture]
        ↓
   AI Service (Calls interpret_qibit & extract_related_entities)
        ↓
  [Insert into ai_outputs] (State: accepted=false)
        ↓
  [Inbox UI Display] (Show suggested fields side-by-side with original text)
        ├─────────────────────────────┐
        ▼                             ▼
  [Cody clicks Edit]            [Cody clicks Accept]
        ▼                             ▼
   Modifies fields in form      Backend writes direct to primary tables
        └──────────────┬──────────────┘
                       ▼
            [Commit to SQLite]
     - Mark ai_outputs.accepted = true
     - Create records in primary tables
     - Create links for provenance

3. Database State Machine

The ai_outputs Table State

• accepted = false (default): Represents a pending suggestion. It is displayed as a draft card in the inbox or context dock.
• accepted = true: Cody has approved this output. The application logic prevents writing this output to the primary tables again to avoid duplicate creation.

Provenance Mapping in links

When a suggestion is accepted:

• A link is written: source_type = 'qibits', source_id = [QiBit ID], target_type = 'actions', target_id = [Created Action ID], relationship = 'created_from'.
• If money is extracted: source_type = 'qibits', source_id = [QiBit ID], target_type = 'obligations', target_id = [Created Obligation ID], relationship = 'created_from'.

4. UI Representation of AI State

The frontend must visually distinguish between three categories of data:

1. Confirmed Data (User Entered/Approved): Standard color coding, fully indexed.
2. Suggested Data (AI Drafts):
   • Displayed with dashed borders or light purple background.
   • Accompanied by a confidence rating indicator (e.g., Confidence: 85%).
   • Features a quick-action checkmark (Accept) and a pencil icon (Edit).
3. Contradictions / Flags: If an AI background process detects an unresolved open loop or a duplicate entry, it places a red warning icon in the Context Dock under "AI Flags".

QiApp QiLife

Overview

QiLife is the private life operating app. It turns life chaos into QiBits that can be captured, triaged, routed, acted on, documented, resolved, reflected on, and retrieved.

Responsibilities

• QiBits.
• Timeline projection.
• Buckets.
• Threads.
• Actions and steps.
• People, money, documents, events, and knowledge items.
• Context Dock.
• Activity log.
• AI outputs and retrieval.

Flows

Capture
  -> Bucket
  -> Interpret
  -> Relate
  -> Slot
  -> Breakdown
  -> Enrich
  -> Act
  -> Resolve
  -> Reflect
  -> Retrieve

Structure

Core v1 tables: qibits, buckets, threads, actions, action_steps, people, transactions, obligations, knowledge_items, documents, events, links, activity_log, ai_outputs, and daily_summaries.

QiAccess Start Overview

This document provides a high-level overview of the repo-side canonical QiAccess Homepage configuration prepared on Cody's local PC. It is not a claim that the live qiserver Homepage config already matches this repo.

1. Verified Facts

• Architecture: Homepage-powered private launcher config under qiaccess/config/.
• Canonical Repo Config Files:
  • qiaccess/config/services.yaml
  • qiaccess/config/bookmarks.yaml
  • qiaccess/config/settings.yaml
  • qiaccess/config/widgets.yaml
• Private Launcher URL: https://qiserver-1.cerberus-sirius.ts.net/
• Public Front Door: https://access.qially.com
• Service URL Set Updated In Repo:
  • Open WebUI: https://qiserver-1.cerberus-sirius.ts.net:9446
  • Paperless-ngx: https://qiserver-1.cerberus-sirius.ts.net:9447
  • Wiki.js: https://qiserver-1.cerberus-sirius.ts.net:9448
  • Portainer: https://qiserver-1.cerberus-sirius.ts.net:9449
  • n8n: https://qiserver-1.cerberus-sirius.ts.net:9450
  • Uptime Kuma: https://qiserver-1.cerberus-sirius.ts.net:9451
  • Qdrant: https://qiserver-1.cerberus-sirius.ts.net:9452
  • NocoDB: https://qiserver-1.cerberus-sirius.ts.net:8443
  • Cockpit: https://100.121.111.106:9090
  • Firefly III: http://qiserver-1.cerberus-sirius.ts.net:6877
  • Firefly Importer: http://qiserver-1.cerberus-sirius.ts.net:6878
  • SolidTime: https://qiserver-1.cerberus-sirius.ts.net:9453
  • Neo4j: http://qiserver-1.cerberus-sirius.ts.net:7474
• Deployment Boundary: The repo config is not live until Server Codex pulls the repo and syncs it into /srv/qios/stacks/_qiaccess_start/config/.

2. Target Hierarchy

• This file is situated in: docs/60_qiapps/qiaccess_start/overview.md.
• References core governance and ADR logs in docs/10_qicore/10_governance/.

3. Actual Runtime / Storage Locations

• Repo Root: c:\QiLabs\_QiAccess_Start\
• Canonical Local Config Path: c:\QiLabs\_QiAccess_Start\qiaccess\config\
• Server Sync Target: /srv/qios/stacks/_qiaccess_start/config/
• Edge URL: https://access.qially.com
• Private Launcher URL: https://qiserver-1.cerberus-sirius.ts.net/

4. Unknowns

• Whether the live server Homepage config still contains custom deviations beyond the URLs captured in this repo pass.

5. Needs Cody Confirmation

• Should repo-side recovery/documentation links remain GitHub-backed, or should they later point at Wiki.js pages after sync/publish is stable?

6. Wiki.js-Ready Summary

QiAccess Start is the repo-maintained canonical Homepage launcher config for Cody's private qiserver utility dashboard. It carries the grouped layout, known Tailscale service URLs, and recovery links, but it does not become live until Server Codex pulls the repo and syncs the config into /srv/qios/stacks/_qiaccess_start/config/.

7. Implementation Notes

• Layout Rule: Preserve the improved Homepage grouping/layout in settings.yaml while using real documented service URLs in services.yaml.
• No Secrets Rule: Do not commit Homepage widget tokens or credentials into repo YAML.
• Deployment Rule: Local repo edits alone do not update qiserver; Server Codex must later pull and sync the config.

Wiki.js Publish Plan

This document details the plan to automatically synchronize static markdown files from the local Git repository to the operational Wiki.js database.

1. Verified Facts

• Wiki.js Endpoint: The active internal endpoint is https://qiserver-1.cerberus-sirius.ts.net:9448 (Tailscale Serve route).
• Public Domain: https://wiki.qially.com exists but suffers from degraded tunnel routing (needs repair).
• API Availability: Wiki.js exposes a GraphQL API for page creations, updates, and indexing.

2. Target Hierarchy

• This file is situated in: docs/60_qiapps/qiaccess_start/wiki_publish_plan.md.
• Interacts with system rebuild scripts in docs/10_qicore/ (e.g. rebuild.bat).

3. Actual Runtime / Storage Locations

• Sync script: Planned to run under _QiAccess_Start/scripts/publish_wiki.py or as an n8n workflow.
• Source Files: Static markdown folders (10_qicore, 20_qinexus, 30_qiarchive) under docs/.
• Target Database: PostgreSQL instances feeding the Wiki.js container on qiserver.

4. Unknowns

• How Wiki.js GraphQL mutations handle page assets (images, pdfs) when referencing local relative directories.
• Best formatting style to map custom front-matter tags (YAML blocks) to Wiki.js tags.

5. Needs Cody Confirmation

• Do we write a custom python synchronization script using requests, or do we implement this as an n8n webhook workflow?
• How frequently should the sync run (e.g. on every Git push or hourly)?

6. Wiki.js-Ready Summary

Wiki.js Publish Plan establishes the requirements and architecture for importing markdown blueprint documents into Wiki.js. It details the GraphQL payload structures, path resolution logic, and edge proxy mappings required to publish governance, schemas, and operational checklists automatically.

7. Implementation Notes

• API Authentication: Requires a Wiki.js API Token with write:pages permission scope.
• Path Translation:
  • Local path docs/10_qicore/10_governance/10_principles/_index.md
  • Maps to Wiki.js route /qicore/governance/principles
• Payload Structure:
  • Query: mutation ($title: String!, $content: String!, $path: String!) { pages { create(title: $title, content: $content, path: $path, description: "Synced doc", editor: "markdown", locale: "en") { page { id } } } }

Local Development Setup

Canonical Local Paths

• backend app root: C:\QiLabs\60_QiApps\_qilife\backend
• frontend app root: C:\QiLabs\60_QiApps\_qilife\frontend
• SQLite database path: C:\QiLabs\60_QiApps\_qilife\data\db\qilife.sqlite

Backend

1. Create and activate a virtual environment.
2. Install backend dependencies from requirements.txt.
3. Start FastAPI with uvicorn app.main:app --reload --host 127.0.0.1 --port 8000.

Python's standard library already includes SQLite support; do not add sqlite3 as a pip dependency.

Frontend

1. Install dependencies in frontend/.
2. Optional: set VITE_API_BASE_URL=http://127.0.0.1:8000.
3. Start Vite on 127.0.0.1:5173.

If VITE_API_BASE_URL is not set, the app stays operational in localStorage fallback mode.

Deployment Doctrine

We use a single API base URL strategy across environments.

• Frontend app: hosted on Cloudflare Pages.
• Backend app: hosted on qiserver running the real FastAPI application with local SQLite.
• Optional gateway: a future Cloudflare Worker may proxy traffic, but it is not the primary backend today.

Frontend API Configuration

• Uses VITE_API_BASE_URL for all backend API calls.
• Local dev example: http://127.0.0.1:8000
• Future qiserver API target: https://qilife-api.qially.com
• Do not hardcode localhost in frontend components.
• On startup, the frontend checks /api/health. If offline, it shows Local fallback mode and uses localStorage for the working loop.

Development Rules

• Treat repo docs/ as canonical system knowledge.
• Keep imported repo docs read-only in the app.
• Do not create a separate wiki service for v1.

Future Docker Deployment Plan

Services

1. Frontend
2. Backend
3. SQLite-backed data volume for v1

Canonical Database Path

Use sqlite:////app/data/db/qilife.sqlite inside the backend container.

Compose Direction

• Mount /app/data as a persistent volume.
• Keep the repo docs mounted or baked into the image so the importer can read docs/.
• Preserve the same database path convention used in local development.

Postgres remains a later migration target, not a v1 dependency.

QiServer Deployment (Future)

This document is a post-v1 deployment target. It should not alter the local-first v1 doctrine.

Canonical Production Data Path

• DB path: /var/lib/qilife/data/db/qilife.sqlite
• backups path: /mnt/backups/qilife

Backup Rule

Use SQLite's online backup API against the canonical path:

sqlite3 /var/lib/qilife/data/db/qilife.sqlite ".backup '/mnt/backups/qilife/qilife_YYYYMMDD_HHMM.sqlite'"

Repo Docs Doctrine

• Repo docs/ remain the canonical authoring source for system knowledge.
• The app imports those docs into knowledge_items as read-only records.
• Reverse sync from in-app edited knowledge to an external markdown vault is out of scope for v1.

Automation Backlog

This backlog tracks automation targets within the QiAccess ecosystem, outlining their implementation priority, dependencies, blockers, and automation readiness scores.

1. Automated Document watched folders intake (QiIngest Core)

Automate the file system watch triggers in the 00_inbox and route them to Paperless-ngx.

• Priority: Critical / High
• Prerequisites: Secure Docker volume binds on qiserver, verification of Tailscale network persistence.
• Blockers: None.
• Automation Readiness: 3.5 / 5 (Tools are ready, but container daemon bindings need configuration).

2. Wiki.js Auto-Publishing API Pipeline

Convert local static Markdown blueprints and records into Wiki.js pages automatically upon push.

• Priority: Medium
• Prerequisites: Wiki.js API token setup and connection path repair on wiki.qially.com.
• Blockers: Public Cloudflare tunnel routing to Wiki.js is currently degraded; private-only 9448 endpoint must be used.
• Automation Readiness: 2.5 / 5 (Wiki.js API is standard, but the connector script needs mapping).

3. Neo4j Graph Extraction & Sync

Generate entity relationship graph files and seed Neo4j with structural metadata.

• Priority: Medium
• Prerequisites: Bring Neo4j back online.
• Blockers: TCP port 7474 did not respond on 100.121.111.106 during the 2026-05-08 audit (marked as broken / offline in registry).
• Automation Readiness: 1.5 / 5 (Database container requires troubleshooting before extraction code can run).

4. Ollama to Qdrant Vector Sync

Automatically chunk ingested files, run embeddings using Ollama embeddinggemma:latest, and upsert vectors to Qdrant collections.

• Priority: High
• Prerequisites: Qdrant collection schemas, chunking rules in docs/30_qiarchive/30_chunking/20_chunk_rules/.
• Blockers: Qdrant configuration is currently a placeholder (needs initialization).
• Automation Readiness: 3 / 5 (Ollama API is verified active; Qdrant container is online but needs collection creation).

5. Uptime Kuma Automated Container Auto-Healer

Configure webhooks from Uptime Kuma to trigger Docker container restarts on qiserver when port monitoring fails.

• Priority: Low
• Prerequisites: Portainer API keys and docker-entrypoint hooks.
• Blockers: Access security checks (ensuring container restarts are restricted to non-malicious sources).
• Automation Readiness: 2.5 / 5 (n8n hooks can route these, but strict auth guards are missing).

Core Workflows

This document defines the core workflows governing the QiAccess ecosystem, specifying trigger conditions, processing steps, reviews, and fallback models.

1. Repository Synchronization (Sync Walk & Doc Rebuild)

Maintains alignment across multiple sub-repositories (QiLabs, QiNexus) and updates static markdown indexes/blueprints.

• Trigger: Manual instruction from operator or daily cron scheduled via agent.
• Input: Local uncommitted changes, updated markdown notes, and schema configs.
• Processor: Git engine, scripts/enforce_structure.py, and docs/10_qicore/rebuild.bat.
• Output: Clean git tree status, rebuilt MkDocs site, updated index snapshots, and remote pushes.
• Source of Truth: Active local workspaces committed and pushed to remote git repositories.
• Human Review Step: Final inspection of Git push status and lint validation output before committing.
• Failure Handling: Stoppage on script compilation error or merge conflict. Keeps changes local, quarantines push errors to repo_push_errors.log.
• Automation Readiness Score: 4.5 / 5 (Highly automated via batch scripts, but requires human approval for resolving conflicts).

2. Care Schema & Clinical Sync (MomsCare Integration)

Coordinates the sync between the local files (e.g. ADHD clinical vaults, discharge PDFs) and operational backend data.

• Trigger: Patient regimen logging or receipt of discharge documents.
• Input: Clinical logs, CPAP records, or ADHD markdown files.
• Processor: CLI Type Generator and local data syncing script.
• Output: Updated TypeScript types, loaded rows in the Care schema, and synced files in the clinical vault.
• Source of Truth: Relational Care Schema (Supabase/Postgres) and markdown file logs.
• Human Review Step: Manual verification of discharge papers and verification of logged doses via the QiAccess UI.
• Failure Handling: Failed sync logs trigger a notification card on the QiAccess homepage; data is quarantined locally.
• Automation Readiness Score: 3.5 / 5 (Schema generation is stable; sync scripts are still custom/ad-hoc).

3. Service Status & Health Monitoring

Monitors docker container bindings, Tailscale IP connectivity, and alerts on degradation.

• Trigger: Five-minute cron job.
• Input: Port listening states, DNS reachability, and Tailscale Serve endpoints.
• Processor: Uptime Kuma (uptime.placeholder.qially.internal) and status widgets.
• Output: Status dot updates (green/red) on the QiAccess homepage and alert channels.
• Source of Truth: Uptime Kuma database and active server binding facts.
• Human Review Step: None for detection; manual intervention needed to launch Cockpit or Portainer for restarts.
• Failure Handling: Automatic Docker container restart policy (restart-unless-stopped) followed by local notification.
• Automation Readiness Score: 4 / 5 (Detection and alert triggers are fully automated; recovery actions are manual).

4. Origin-Down Triage (Recovery Fallback)

Restores portal access and triages service interruption when qiserver goes offline.

• Trigger: Edge connection timeout (Cloudflare Gateway failover).
• Input: Cloudflare routing health metrics.
• Processor: Cloudflare edge network rules.
• Output: Fallback routing redirecting access.qially.com to the offline static fallback page.
• Source of Truth: Edge configuration rules and recovery notes cached in the browser/CDN.
• Human Review Step: Operator manually opens the SSH console or Cockpit recovery console to diagnose machine states.
• Failure Handling: Fallback to Tailscale Direct IP connection to bypass DNS/proxy failure.
• Automation Readiness Score: 2 / 5 (Failover detection is automated, but origin diagnosis is entirely manual).

title: QiIngest Pipeline status: planned updated: 2026-05-26

QiIngest Pipeline

Purpose

QiIngest Pipeline is the future local-first ingestion workflow for documents and document-like artifacts. This page is architecture and planning only. It does not claim that the full pipeline already exists in this repo.

Goal

Build a controlled local-first path that can:

1. watch selected folders
2. hash files
3. detect duplicates
4. import documents into Paperless
5. extract text and OCR results
6. classify documents by content and context
7. propose cleaned filenames
8. propose metadata, tags, correspondents, and document types
9. update a file inventory
10. embed document text into a vector store such as Qdrant
11. optionally map entities and relationships into Neo4j
12. create an approval queue for Cody
13. update routing rules based on Cody-approved corrections
14. improve routing accuracy over time

Current Repo Reality

What Exists

• Paperless is already treated in repo docs as the first real ingestion target.
• docs/10_qicore/50_operations/20_qiserver/_index.md documents the Paperless 10-document test rule before bulk import.
• docs/10_qicore/50_operations/30_dev_history/2026-05-17_open_loop_reset_paperless_ingestion_runbook.md outlines a controlled staging and manifest concept for Paperless.
• docs/30_qiarchive/10_ingestion/, 20_extraction/, 40_embeddings/, and 50_graphs/ contain placeholder planning folders.

What Does Not Exist In This Repo

• no committed folder watcher for QiIngest
• no committed duplicate-detector for QiIngest
• no committed Paperless staging script for QiIngest
• no committed OCR or text extraction worker for QiIngest
• no committed classifier or filename-normalizer for QiIngest
• no committed inventory database or inventory writer for QiIngest
• no committed Qdrant writer for QiIngest
• no committed Neo4j mapper for QiIngest
• no committed approval queue implementation for QiIngest

Important Non-Match To Avoid

• src/pages/api/hash.js is a Homepage config hash endpoint, not a file-ingest hashing pipeline.

Proposed Pipeline Stages

Stage 1: Watch And Register

Input:

• approved local folders
• manual drop zones
• optionally exported document batches

Actions:

• detect new or changed files
• compute stable hash values
• record source path, timestamps, size, and file type
• check duplicate history before deeper processing

Output:

• inventory registration record
• staging decision: new, duplicate, skip, manual review

Stage 2: Paperless Intake

Actions:

• stage safe copies into Paperless consume flow
• keep originals untouched until verified
• follow the 10-document maximum proof step before bulk import

Output:

• Paperless import receipt
• initial document identity linkage back to the local inventory

Stage 3: OCR And Text Extraction

Actions:

• capture OCR text from scans
• extract text from native digital documents when available
• preserve raw extracted text plus cleaned text

Output:

• raw text
• cleaned text
• extraction status

Stage 4: Classification And Naming Suggestions

Actions:

• classify by content, source context, and historical routing patterns
• propose cleaned filenames
• propose tags, correspondents, document types, and routing targets

Output:

• suggestion set, not silent auto-rename

Stage 5: Inventory And Derived Layers

Actions:

• update the file inventory with canonical facts
• write embeddings to Qdrant or another approved vector store
• optionally create Neo4j entity and relationship projections

Rule:

• inventory facts stay canonical
• vectors and graph remain derived

Stage 6: Approval Queue And Learning Loop

Actions:

• queue proposed corrections for Cody review
• record Cody-approved edits
• update routing rules from approved corrections only
• keep audit trail of changed rules and their source decisions

Suggested Data Artifacts

Verified Facts

• The repo already documents Paperless as the first real ingest lane.
• The repo already documents vector and graph layers as downstream/derived concepts.
• No full QiIngest implementation scripts are committed here today.
• Existing related tooling in this repo is limited to documentation audit and Homepage config-map generation.

Assumptions

• Local-first means the first detection, hashing, staging, and approval loop should start from Cody-controlled folders or drop zones.
• Paperless should be the first durable document-ingest system before vector or graph expansion.
• Qdrant and Neo4j should remain optional downstream layers, not required first milestones.

Unknowns

• Which local folders should be watched first.
• Where the inventory should live.
• Which approval queue surface Cody wants to use.
• Whether filename cleanup should happen before or after Paperless import.
• Whether routing rules should stay file-based, database-backed, or both.

Needs Cody Confirmation

• Initial watch-folder set.
• Preferred approval queue surface.
• Preferred inventory location.
• Whether Paperless should stay the first mandatory destination for all document-like material or only a subset.

Repo-Only Content

• Exact source references to current runbook docs and placeholder archive folders.
• Warning that src/pages/api/hash.js is unrelated to QiIngest.
• Local implementation gap inventory.

Wiki.js-Ready Content

• Stage-by-stage ingest overview.
• Manual-approval rule.
• Canonical-versus-derived rule.
• Paperless-first validation rule.

Future Automation Candidates

• folder watcher
• duplicate detector
• Paperless staging script
• OCR/extraction worker
• classifier and metadata suggester
• inventory writer
• Qdrant writer
• optional Neo4j mapper
• approval queue UI or CLI
• correction-to-routing-rule updater

QiConnect

Overview

QiConnect is the integration and access-boundary layer. It documents how Qi services connect to each other, to external providers, and to protected entrypoints.

Responsibilities

• External integrations.
• API and webhook boundaries.
• Public restricted access paths.
• Private-only access paths.
• Tailscale and Cloudflare Access patterns.
• Service-to-service connection notes.
• Integration safety rules.

Flows

External request
  -> DNS, policy, or tunnel endpoint
  -> protected QiServer route
  -> target service
  -> internal data service if required

Structure

Access classes are Private Only, Public Restricted, and Public Safe. Known connection surfaces include Cloudflare Access, Tailscale, localhost verification ports, Docker Compose networks, API endpoints, and webhooks.

Codex Build Prompt v1

You are building the first phase of QiLife, an AI Life Copilot with a Personal LifeDesk cockpit.

DO NOT begin with generic CRUD screens. Build the final scaffold and first vertical slice:

Capture → Ingestion → Mock Agent Draft → Draft Review → Approval → QiBit → Timeline → Activity Log → Context Dock placeholder

Ensure all work aligns with the new Agent-First Doctrine. The repo uses React and Vite. Database is local SQLite.

Review the docs in docs/ for specific architecture decisions before starting:

• docs/10_product/05_agent_first_product_doctrine.md
• docs/40_ui_flows/01_capture_ingestion_review_flow.md
• docs/90_decisions/0009_agent_first_copilot_cockpit.md

Codex Prompt: Documentation Consistency Review

You are an expert software architect and systems analyst specializing in local-first personal productivity systems. Your task is to perform a comprehensive validation check on the entire documentation suite for QiLife.

Instructions

1. Read and Analyze the files in the following directory:

   • docs/ (Overview, Product, Architecture, Data Model, UI Flows, Modules, AI Layer, Deployment, and Decisions)

2. Verify Naming Rules: Ensure the following concepts are used with exact case-sensitivity and terminology across all files. Flags any deviation (e.g., "qibit" or "lifedesk" lowercase, "project" instead of "Thread" when referring to ongoing cases, or "wiki" instead of "Context Dock"):

   • QiLife (The product)
   • QiBit (The atomic data unit)
   • Personal LifeDesk (The operating model)
   • Timeline (The spinal ledger)
   • Bucket (The top-level categorization domain)
   • Thread (The case/ongoing project)
   • Action (The task ledger item)
   • Step (The subtask list item)
   • Context Dock (The contextual sidebar widget)
   • Ask QiLife (The retrieval layer)

3. Check Structural Integrity:

   • Do the database schema fields in docs/30_data_model/ match the definitions and descriptions in the docs/50_modules/ overview files?
   • Are the AI service functions defined in docs/60_ai_layer/ consistent with how AI behaviors are referenced in docs/50_modules/ module files?
   • Are the bucket code definitions consistent across information architecture, data models, and module specifications?

4. Detect Gaps & Risks:

   • Identify any missing details in the database schemas or relationship maps.
   • Identify potential bottlenecks in the "Human-in-the-loop" AI review workflow.
   • Highlight any over-engineered components that violate the "Spine-first / No bank sync / No calendar sync" constraint of V1.

Expected Output Format

Provide your evaluation as a Markdown report containing:

• Executive Summary: Overall readiness score for the V1 build.
• Terminology Deviations: Table showing file name, line number, incorrect term, and expected term.
• Structural Discrepancies: Description of any misaligned tables, schemas, or service definitions.
• Gaps & Recommendations: Bullet points outlining critical missing specs or logical loops.
• Build Readiness Status: [READY TO BUILD] or [REVISION REQUIRED].

Codex Prompt — Will Be Done Research Pass

Research and inspect the Will Be Done repository at:

https://github.com/will-be-done/will-be-done

Do not fork, copy code, or modify files yet.

Goal:

Evaluate Will Be Done as a UX and architecture reference for QiLife.

QiLife is Cody's personal local-first LifeOps / Personal LifeDesk app. It is inspired by helpdesk workflows and Will Be Done's weekly planning feel, but QiLife has a broader data model: QiBits, timeline, buckets, threads, actions, people, money, obligations, notes, documents, knowledge, Context Dock, and AI-assisted triage/retrieval.

Investigate:

1. Frontend stack and component organization.
2. Weekly timeline implementation.
3. Task drag/drop implementation.
4. Project/board model.
5. Quick capture/stash implementation.
6. Local-first/offline data layer.
7. Docker/self-hosted deployment.
8. API/MCP possibilities.
9. AGPL/source attribution implications.
10. What ideas can be emulated without copying code.
11. Whether a personal fork would be safe/useful, or whether QiLife should be a clean separate build.

Deliver:

• repo structure summary
• stack summary
• data model summary if discoverable
• UX patterns to emulate
• code areas not to touch/copy yet
• license notes
• recommendation: fork, reference only, or clean-room rebuild
• QiLife implementation implications

Do not modify files.

ADR 0001: Personal LifeDesk Model

Status

Accepted

Context

Cody's daily life operations (LifeOps) involve tasks, legal issues, financial obligations, documentation, and relationships. Managing these using generic tools (Trello, standard todo apps, spreadsheets) creates fragmentation and cognitive overload. There is no unified metaphor that brings these elements together in a way that respects their interconnected nature (e.g., how a financial loan relates to a specific person and a legal dispute).

Decision

We will standardize the entire application architecture on the Personal LifeDesk model. Under this model:

• The application behaves like an IT/customer helpdesk console.
• Cody is the sole "agent" (the one resolving items) and the primary "customer" (the one whose life is being managed).
• All other individuals, agencies, and vendors are treated as external requesters/contacts.
• The data model maps exactly to helpdesk concepts:
  • Ticket = QiBit
  • Queue/Department = Bucket
  • Case/Project = Thread
  • Work Order = Action
  • Subtask = Step
  • Sidebar widget = Context Dock

Consequences

• Simplicity: The backend database and routing are simplified. There is no need for complex multi-tenant row-level security or multi-user permission roles in V1.
• Strict Vocabulary: Developers and AI agents must strictly use the terms: QiLife, QiBit, Personal LifeDesk, Timeline, Bucket, Thread, Action, Step, Context Dock, and Ask QiLife.
• Narrow Scope: We will not build complex Customer Relationship Management (CRM) sales pipelines or client portals.

ADR 0002: QiBit as the Atomic Unit

Status

Accepted

Context

User inputs vary drastically in format (a text message, a scan of a legal notice, a voice memo, a transaction log). Attempting to immediately force these into rigid schemas (like forcing a vague text "Zai gas $40" directly into a double-entry accounting ledger or a calendar deadline) leads to capture friction. People stop capturing items if the entry form is too demanding.

Decision

We will establish the QiBit as the atomic unit of all data within QiLife.

• Every capture action creates a QiBit first.
• A QiBit contains a raw_capture field to preserve the exact raw input text, and metadata tracking when and how it was captured.
• All structured operational records (Actions, Obligations, Transactions, Documents) must link back to a parent QiBit to preserve historical provenance.

Consequences

• Zero-Friction Ingestion: Cody can capture thoughts or logs in a single input field.
• Staged Structure: Separation of capture from organization. AI or manual triage processes run asynchronously or semi-synchronously to unpack the QiBit into structured tables without blocking ingestion.
• Provenance Retention: Clicking on any Action or Transaction allows Cody to trace it back to the exact raw text or situation that triggered it.

ADR 0003: Timeline as the Spine

Status

Accepted

Context

When reviewing tasks, logs, or transactions, we often lose the surrounding context of when things occurred in relation to other events. For example, knowing that a gas bill was paid on May 15 is useful, but seeing it on a visual timeline next to a Lyft driving log and a chat summary from that same day provides immediate explanatory value.

Decision

We will establish the Timeline as the spinal core of the QiLife interface and data queries.

• Every record that participates in the timeline must expose either a canonical timestamp field or a deterministic projection rule.
• The primary interface view is a chronological feed where QiBits, note/reflection-type QiBits, transactions, completed actions, events, and daily summaries can be displayed sequentially.
• The UI must support unified filtering across all entity types based on temporal queries.

Consequences

• Contextual Coherence: Cody can scroll back to any date and see a comprehensive picture of what happened, who was involved, and what money moved on that specific day.
• Projection Rules: The backend must define which timestamp each entity uses when rendered in the feed.
• Interface Unity: Rather than having isolated dashboard silos, the various modules feed their output into the Timeline.

ADR 0004: Context Dock Over Wiki

Status

Accepted

Context

Durable knowledge (such as operating procedures, billing rules, contact directories, and decision logs) is normally stored in a separate, isolated wiki space (like Notion or Wiki.js). This creates friction because Cody must context-switch to find the relevant instructions while working on a task. Consequently, wiki documentation is rarely read or updated, leading to operational errors.

Decision

We will not build or host a separate wiki engine. Instead, we will store knowledge directly inside the QiLife database (knowledge_items) and expose it through a persistent, collapsible sidebar panel called the Context Dock.

• The Context Dock automatically queries and displays knowledge, linked documents, related people, and prior resolutions relative to the item Cody has open in the center workspace.
• Knowledge is co-located with action: Cody can read the guide on how to request a check reissue in the Context Dock while checking the status of his Action in the center workspace.

Consequences

• Reduced Context Switching: Cody has all the information needed to complete a task directly on-screen.
• Simpler Architecture: We avoid the overhead of deploying and maintaining a third-party wiki service (e.g., Wiki.js) and trying to synchronize auth states.
• Contextual Queries: Developers must build relation-based database queries that pull records matching active tags, buckets, threads, or people.

ADR 0005: Repo Docs Indexed in App

Status

Accepted

Context

During the design and build phases, repository markdown documentation (located in docs/) is the canonical source of truth for developer agents (like Codex or Antigravity) to understand system specifications. However, when Cody operates the live QiLife app in production, he needs access to these design docs, user flows, and guidelines. Manually copying markdown files into database editors is highly inefficient and creates sync issues.

Decision

We will treat the markdown files in the repository's docs/ folder as the canonical authoring source for system-level knowledge. The application will include an automated importer/syncer script that:

• Crawls docs/ at startup or via admin command.
• Parses the frontmatter and markdown body of each file.
• Compares the MD5 hash of the file with the database record (sync_hash).
• Inserts or updates the content into the knowledge_items table with source_type = 'repo_doc'.

Consequences

• Single Source of Truth: System design, schemas, and ADRs are authored in git as code, but made instantly readable inside the app.
• RAG Coverage: The indexed repository documents are fully searchable via the Ask QiLife semantic engine, allowing Cody to query system operations directly (e.g. "What is the database schema for obligations?").
• Read-Only App View: Imported repository documents are marked as read-only within the browser UI to prevent writes in the app from contradicting the files in git.

Decision 0006: Clean Core with Legacy Bridge

Context

QiLife is replacing an older Supabase-backed system that has a messy schema.

Decision

QiLife will use a clean canonical schema locally in SQLite, avoiding inheritance of the old Supabase schema chaos. A Legacy Data Bridge will be built to map and selectively import useful records as legacy QiBits.

Consequences

• Supabase is no longer the runtime source of truth.
• We need explicit bridge tables (legacy_sources, legacy_tables, etc.).
• The core data model remains clean and agent-friendly.

Decision 0007: App-Managed Storage and Sync

Context

Managing files and syncing manually across folders is brittle and error-prone.

Decision

QiLife will act as a control center managing its own storage footprint (DB, file vault, exports). Folders will be projections of metadata rather than the source of truth.

Consequences

• Eliminates manual folder management.
• Requires building storage management and health check features.
• Clear separation between repo (code), private data (DB/files), and exports (Drive/QiNexus).

Decision 0008: Managed Document Vault (Dup-Allergic)

Context

Ingesting the same documents multiple times creates noise and fragments context.

Decision

QiLife will implement a managed document vault that hashes every incoming file. The system will be dup-allergic, preventing duplicate blobs and flagging near-duplicates.

Consequences

• Meaningful documents are separated from raw file objects.
• Requires building hashing, duplicate candidate review, and versioning flows.
• Allows safe, restorable deletion before purging.

Decision 0009: Agent-First Copilot Cockpit

Context

QiLife was initially envisioned as a manual CRUD app with AI features.

Decision

QiLife is fundamentally an AI Life Copilot with a Personal LifeDesk cockpit. The agent is the core product, and the UI is its control panel.

Consequences

• Manual CRUD forms are secondary.
• Primary interaction flows through capture, AI drafting, and human review.
• The UI focuses on open loops, AI drafts, and the timeline.

Decision 0010: Spaces for Scoped Shared Access

Context

QiLife needs to support Mom Care notes without building a separate app or a bloated clinical EMR.

Decision

Use Spaces to provide scoped shared access. Mom Care will be a space with specific access roles. Everything defaults to Cody Private, and items are explicitly shared.

Consequences

• Simplifies architecture by using one backend for multiple contexts.
• Avoids overbuilding an EMR. Focuses on lightweight buckets and timeline notes.
• Private notes can safely generate sanitized shared Care Notes.

Current Project State

Last inspected: 2026-05-29 on qiserver.

Confirmed State

• QiAccess Start is deployed and working.
• The actual deployed runtime path is /srv/qios/stacks/_qiaccess_start.
• The tracked repo used for pull/build handoff is /srv/qios/apps/_QiAccess_Start.
• The confirmed repo remote is git@github.com-qidocs:qiallyme/_QiAccess_Start.git.
• The confirmed branch is main.
• The confirmed deployment method is Docker Compose running Homepage:
  • project: qiaccess_start
  • compose file: /srv/qios/stacks/_qiaccess_start/docker-compose.yml
  • container: homepage
  • image: ghcr.io/gethomepage/homepage:latest
  • local port: 127.0.0.1:3001 -> 3000

Codebase Structure Summary

• App framework: Homepage/gethomepage-derived Next.js dashboard branded as QiAccess.
• src/: React views, routing, layout, and registry states.
• qiaccess/: Homepage deployment config tracked in Git.
• worker/: Cloudflare edge worker configs for static/offline paths and CRUD bookmark planning.
• docs/: Canonical documentation tree and operational receipts.

Config Merge And Deployment Receipt

The repo config files under /srv/qios/apps/_QiAccess_Start/qiaccess/config were merged using:

• live config as the source of truth for real working service URLs
• repo config as the source of truth for future-state grouping, layout, and styling

Updated repo files:

• qiaccess/config/services.yaml
• qiaccess/config/bookmarks.yaml
• qiaccess/config/settings.yaml
• qiaccess/config/widgets.yaml

The reviewed repo config was synced into the live stack config:

• /srv/qios/stacks/_qiaccess_start/config/services.yaml
• /srv/qios/stacks/_qiaccess_start/config/bookmarks.yaml
• /srv/qios/stacks/_qiaccess_start/config/settings.yaml
• /srv/qios/stacks/_qiaccess_start/config/widgets.yaml

Backup created before sync:

• /srv/qios/stacks/_qiaccess_start/backups/config_20260528_232052/

After sync, homepage was restarted through the confirmed qiaccess_start compose stack.

Live Verification Receipt

Verified after sync:

• homepage was healthy.
• http://127.0.0.1:3001 returned 200 OK.
• https://qiserver-1.cerberus-sirius.ts.net returned 200 OK.
• https://access.qially.com returned a Cloudflare Access login redirect for unauthenticated access.
• /api/services returned the merged groups: QiAccess, Core Services, Knowledge + Archive, Data + Workflows, Finance, Server Control, Attention + Recovery.

Handoff Notes

• /srv/qios/repos/_QiAccess_Start also exists, but it is not the confirmed deployment checkout.
• /srv/qios/stacks/_qiaccess_start/docker-compose.yml contains sensitive Cloudflare tunnel material in the cloudflared stack area. Do not copy secrets into docs or chat.
• Server-side docs and config changes should be committed and pushed back to GitHub to avoid divergence from the local PC checkout.
• Older repo notes about placeholder URLs are superseded by the merged config and server verification receipts.

Server Codex Follow-Ups

1. Keep /srv/qios/apps/_QiAccess_Start as the pull/build handoff checkout unless Cody decides otherwise.
2. Do not deploy from /srv/qios/repos/_QiAccess_Start without reinspection.
3. For future config changes, back up /srv/qios/stacks/_qiaccess_start/config, show the diff, sync only reviewed files, restart only homepage, and verify routes.

ADR-0011: Homepage-Powered QiAccess

Status

Accepted locally on 2026-05-24.

Context

QiAccess had drifted into multiple overlapping implementations, including a custom React portal, a legacy Homepage-style local launcher, static site material, and generated documentation artifacts. The active direction is now a branded Homepage dashboard hosted on QiServer.

Decision

• QiAccess is no longer the custom React portal.
• Homepage is the canonical dashboard runtime for QiAccess.
• The cloned Homepage source tree remains intact at the repo root.
• Active deployment config lives under qiaccess/.
• Legacy material remains under .legacy/ for reference only.
• Cloudflare owns access.qially.com routing and should present a static offline/recovery page when QiServer is unavailable.

Consequences

• Dashboard changes should prefer YAML configuration and light custom.css polish over source-code edits.
• Terminal, Cockpit, and Portainer remain the real control surfaces for server actions.
• Legacy material may be salvaged selectively, but it is not part of the active runtime without an explicit documented decision.

CODEX SYSTEM CONTROL FILE

🔴 SECTION 0 — ACTIVE INSTRUCTIONS

• Always reconcile existing systems before creating new ones
• Prefer reuse over new implementation
• Identify contradictions explicitly
• Separate facts vs assumptions
• Do NOT implement unless explicitly instructed
• Always read this file fully before acting

🟡 SECTION 1 — ACTIVE AUDIT QUEUE (NEWEST FIRST)

[AQ-001] Relationship Intelligence / Trust Tracking

Status: Pending
Created: 2026-06-09

Context:
Need system to track individuals, interactions, and derive trust/reliability.

Ask Codex:

• What exists in DNA/docs for:
  • entity tracking
  • interaction/event logs
  • trust/reliability evaluation
• Where is it located?
• Is it complete, partial, or conceptual?
• Are there contradictions?
• What’s missing?

Constraints:
Audit only. No building.

🟢 SECTION 2 — RESOLVED / ARCHIVE

(None yet)

title: Home description: A modern, fully static, fast, secure, fully proxied, highly customizable application dashboard with integrations for over 100 services and translations into multiple languages. icon: material/home hide: - navigation - toc - path

A modern, fully static, fast, secure fully proxied, highly customizable application dashboard with integrations for over 100 services and translations into multiple languages. Easily configured via YAML files or through docker label discovery.

QiLinks Bookmark Admin Plan

Purpose

QiAccess/Homepage remains the display layer.

QiLinks is a small admin-only helper for managing Homepage configuration, starting with qiaccess/config/bookmarks.yaml so bookmark changes do not require direct YAML editing for every routine update.

QiLinks is not a replacement for Homepage, not a revival of the old React QiAccess portal, and not a public-facing application.

Access Boundary

• QiLinks should be admin-only.
• Preferred access:
  • Tailscale-only
  • or Cloudflare Zero Trust protected
• It should not be exposed as a public editor on access.qially.com without an explicit later decision.

Current Config Reality

Active Homepage config lives under:

• qiaccess/config/settings.yaml
• qiaccess/config/services.yaml
• qiaccess/config/bookmarks.yaml
• qiaccess/config/widgets.yaml
• qiaccess/config/docker.yaml

Current bookmarks are still placeholder-oriented, which makes bookmark editing a good first scope for a helper tool.

Initial Scope

Initial QiLinks scope should be narrow:

• add bookmark
• edit bookmark
• delete bookmark
• choose or create bookmark group
• preview normalized bookmark data before write

This first version should update only bookmarks.yaml.

Later Scope

Later scope can expand carefully into:

• services.yaml
• widgets.yaml
• icon selection / icon validation
• group management and reordering
• schema validation / linting
• import/export helpers
• access tags and environment-specific filtering

Save Behavior

QiLinks should write YAML safely:

1. Read and parse the current bookmarks.yaml.
2. Normalize data into an internal bookmark model.
3. Create a timestamped backup before writing.
4. Write the updated YAML atomically where practical.
5. Preserve formatting and ordering where possible.

Recommended backup pattern:

• store backups under qiaccess/config/_backups/
• use a timestamped filename such as:
  • bookmarks_2026-05-24T06-15-00.yaml

Formatting note:

• Plain PyYAML is acceptable for a first CLI helper, but it may not preserve comments and exact formatting.
• If formatting preservation becomes important, move to a round-trip YAML library later.

Validation Behavior

QiLinks should validate before and after write:

• parse current YAML before any edit
• reject invalid or incomplete bookmark records before write
• write to a temp path first when possible
• parse the newly written YAML again after write
• only replace the active file if the post-write parse succeeds

Minimum validation checks:

• group is present
• name/title is present
• href is present
• href uses a safe URL or approved scheme
• abbr and icon are optional, but Homepage rules should be respected

Restart / Reload Behavior

Homepage behavior differs by config type:

• settings.yaml:
  • local docs say settings changes require regenerating static HTML, typically via the refresh icon in the lower-right UI
• local icons / images:
  • local docs say adding new image files may require a container restart
• bookmarks.yaml, services.yaml, widgets.yaml:
  • Homepage reads these configs through its config helpers and API routes
  • in practice, changes should be treated as requiring at least a Homepage revalidate/refresh cycle

Safe operational rule for QiLinks:

1. write YAML
2. validate write
3. call Homepage revalidate if the helper is colocated with the app
4. if visual state does not update, use the built-in Homepage refresh action
5. restart the container only when image or static asset behavior requires it

QiLinks should document this honestly rather than promising live hot-edit behavior everywhere.

Proposed Bookmark Schema

Homepage bookmark YAML is group-based and compact, but QiLinks should use a clearer internal schema:

group: External / Mobile Functions
name: Google Drive / QiNexus
href: https://drive.google.com/
icon: null
abbr: QD
description: QiNexus workspace placeholder
tags:
  - storage
  - qinexus
visibility:
  access: external
  notes: Public web link, daily-use surface

Recommended fields:

• group
• name/title
• href
• icon
• abbr
• description
• tags
• visibility/access notes

Mapping notes:

• group, name, href, icon, abbr, and description map naturally into Homepage YAML
• tags and visibility/access notes do not map directly into current Homepage bookmark rendering
• for now those extra fields should live in QiLinks metadata only, or later in a sidecar file if needed

Proposed Interface

The first implementation should be a CLI or protected admin helper, not a public web app.

Suggested command shape:

• qilinks list
• qilinks add
• qilinks edit
• qilinks delete
• qilinks backup
• qilinks validate

Suggested edit flow:

1. select group
2. select bookmark or create new
3. edit fields
4. preview resulting YAML shape
5. backup
6. write
7. validate
8. optionally trigger Homepage revalidate

Visual Map Generator Plan

The visual map should be generated, not hand-maintained.

Inputs:

• qiaccess/config/bookmarks.yaml
• qiaccess/config/services.yaml
• qiaccess/config/widgets.yaml
• optionally qiaccess/config/settings.yaml for title and group ordering context

Outputs:

• Mermaid mind map or flow map
• Markmap-compatible markdown

Write targets:

• _audit/qiaccess_map.mmd
• _audit/qiaccess_map.md

Generation behavior:

1. read YAML inputs
2. extract groups, bookmarks, services, and widgets
3. build a simple tree rooted at QiAccess
4. emit Mermaid and Markdown outputs
5. regenerate whenever config changes

The map should be treated as a derived artifact, not hand-edited source.

Recommended Rollout

Phase 1:

• keep Homepage as-is
• add QiLinks CLI helper for bookmarks only
• add generated visual map output

Phase 2:

• add safe editing for services.yaml
• add validation and optional sidecar metadata

Phase 3:

• add a protected admin UI only if the CLI stops being sufficient

Non-Goals

• no Homepage replacement
• no public bookmark editor
• no old QiAccess portal revival
• no direct server deployment work in this phase

1_QiEos — Core System

Last updated: 2025-10-25

Sections

• [[1_Protocol/README|Protocol & Standards]]
• [[2_Templates/README|Master Templates]]
• [[3_Site/README|Core Site Template]]
• [[4_RAG/README|Chatbot Configs]]
• [[9_Meta/README|Meta Index]]

[[README|⬆ Back]]

QiOS DNA

QiOS DNA is the portable master manual for the QiOS ecosystem.

It preserves the origin doctrine, system map, rules, schemas, decisions, receipts, and reconciliation work needed to understand or rebuild the system.

Core doctrine

• QiOS = the overall ecosystem / operating system.
• QiEOS = the origin brain / DNA / doctrine layer.
• QiOS Start = the cockpit / launcher / front door / docs surface.
• QiSystem = rules, schemas, naming, database doctrine, and lifecycle rules.
• QiServer = infrastructure, runtime, Docker, Cloudflare, monitoring, and backups.
• QiCapture = ingestion, OCR, parsing, embeddings, and pipelines.
• QiNexus = storage backbone and file system model.
• QiApps = standalone apps, sites, and tools.
• QiConnect = external integrations, APIs, workers, and connector surfaces.

Locked QiLabs structure

C:\QiLabs\
  .github\
  .qios\
  .vscode\
  00_QiEOS\
  10_QiOS_Start\
  20_QiSystem\
  30_QiServer\
  40_QiCapture\
  50_QiNexus\
    My Drive\
  60_QiApps\
  70_QiConnect\
  packages\
  scripts\
  toolbox\

Repo rule

This repo mirrors the QiLabs root logic for doctrine and documentation. It is not the actual file-storage root and does not duplicate the full QiNexus My Drive bucket system.

Raw imported docs stay under:

00_QiEOS/receipts/raw_imports/

Canonical doctrine is promoted only after review.

Truth rule

Raw imports are evidence.
Canonical docs are law.
Exports are snapshots.

Site

Overview

site/ contains the single-page system mirror viewer.

Responsibilities

• Render all active _folder.md files into one scrollable HTML page.
• Provide a location-based navigation tree.
• Preserve the physical folder hierarchy visually.

Flows

Open site/index.html
  -> navigation tree loads
  -> click folder link
  -> scroll to matching rendered _folder.md section

Structure

site/
├── _folder.md
├── index.html
├── script.js
└── style.css