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.

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/
├── _folder.md
└── QiEOS/
    └── _folder.md

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.

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.

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

Mirrored documentation filesystem for the Qi system. Every active folder contains one _folder.md. The single-page viewer is site/index.html.

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