START HERE: DSOM Project Benefits & Entry Points
Welcome to the Deep State of Mind (DSOM) For My AI framework. If you are adopting this repository to bootstrap a new infrastructure/software project, or onboarding a new human team member or AI agent, you must understand how to enter the system.
DSOM is a modular Sovereign AI Engine. To use it effectively, do not read every file at random. Start with the defined Entry Points depending on your role.
🌐 Zero-Clone / Zero-Pull Direct Reading via GitHub Pages URLs
If you or your AI agent do not want to git clone or git pull this repository, you can ingest the framework directly via live, HTTPS-hosted GitHub Pages URLs:
🧭 The Diátaxis Documentation Compass: How to Navigate DSOM
Following the Diátaxis Documentation Framework, DSOM documentation is organised across two fundamental axes: Learning vs. Working (Acquisition vs. Application) and Practical vs. Theoretical (Action vs. Knowledge).
Use this compass to jump directly to the exact information you or your AI agent need:
🌟 Why Adopt DSOM in Your Project? (Core Architectural Benefits)
Adopting the DSOM protocol into any new or existing project delivers four transformative capabilities:
| Core Capability / Benefit | How DSOM Achieves It | Empirical Impact / Value |
|---|---|---|
| 1. 98%+ Token & Cost Reduction | OKF YAML Frontmatter + Native OpenWiki (./openwiki/) pre-distil codebase structures into lightweight metadata and 10 concept nodes. |
AI agents search metadata in ~50 tokens instead of loading 500,000+ raw code tokens into context windows. |
| 2. Zero Memory Loss Across Sessions | Spatial Memory (.agents/brain/) records session walkthrough anchors (task.md, walkthrough.md, palace_registry.md). |
AI digital twins (Gemini, Jules, Claude) reanimate instantly with exact past mental state across chat reboots. |
| 3. Zero-Binary & Zero-Cost Portability | Native Python scripts (uv run python tools/openwiki_emulator.py) replace heavy Node.js binaries and third-party APIs. |
Bypasses NODE_MODULE_VERSION native compilation crashes, UAC elevation hangs, 135 MB bloat, and LLM API rate limits. |
| 4. Multi-Agent Cognitive Alignment | 27 Constitutional AI Laws (AGENTS.md) + FastMCP Knowledge Server (tools/mcp/server.py). |
Google Jules, Antigravity, Cursor, and Claude Desktop share identical rules, security guardrails, and test contracts. |
1. The Engineering Entry Point (Project Scaffolding & Team Masterclass)
If you are setting up a brand new DSOM project repository for the first time or onboarding an engineering team.
Read This First (Scaffolding Blueprint): HOWTO-CLONE-DSOM-PROJECT.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/HOWTO-CLONE-DSOM-PROJECT/)
Complete Team Curriculum & Pair-Programming Playbook: tutorials/TEAM-DSOM-MASTERCLASS.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/tutorials/TEAM-DSOM-MASTERCLASS/)
Why it matters: This provides both the theoretical blueprint and concrete terminal scripts (PowerShell / Bash) as well as AI prompting templates (for Google Antigravity). It guides your team through the entire 4-phase lifecycle: creating the 6-pillar downstream directory tree, initializing dual-remote GitOps (GitHub + GitLab), pair programming with Antigravity, and syncing with Google Jules.
2. The Cognitive Entry Point (AI Persona & Rules)
If you are an AI agent, or a human programming an AI agent, and need to know the operational rules of this environment.
Read This First (Root Gateway): AGENTS.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/AGENTS/)
Then Read the Full Rulebook: .agents/AGENTS.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/.agents/AGENTS/)
Why it matters: The root AGENTS.md is the Gateway File for AI agents such as Google Jules, Cursor, and Copilot that scan the repository root. It summarises the DSOM protocol and immediately redirects agents to .agents/AGENTS.md — the Sovereign Constitution containing all 27 operational laws, the LinuxMalaysia persona, the Defensive GitOps rules, the OKF mandate, and the UK English writing standard. Keep both files synchronised at all times.
3. The External System Entry Point (AI Crawlers)
If you are using an external tool (e.g., Google NotebookLM, ChatGPT) to ingest this repository.
Read This First: llms.txt (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/llms.txt)
Why it matters: Placed at the root of the repository, this file acts as the official AI Sitemap. It explicitly links to all the critical governance documents (including the NOSS-INTEGRATION-GUIDE.md) so that external systems immediately understand the architectural constraints and compliance payloads of the project without getting lost in code files.
4. The Daily Operations Entry Point (Day 2 Management)
If the project is already running, and you are starting your work day or recovering from a server reboot.
Read This First: HOWTO-PALACE-ONBOARDING.md
Why it matters: This teaches the human and the AI how to read the palace_registry.md ledger during the Start of Day (SOD) ritual. It ensures the AI never suffers from memory loss between sessions by strictly governing thread states through spatial memory.
5. The Legacy Upgrade Entry Point (Existing DSOM Projects)
If you are operating a legacy DSOM project and need to modernize it to the current master architectural baseline.
Read This First: HOWTO-UPGRADE-LEGACY-DSOM.md
6. The Subagent Swarm Entry Point (Multi-Agent Orchestration)
Entry Point 3: The Native MCP Server Integration
DSOM acts as its own Model Context Protocol (MCP) server (tools/mcp/server.py), allowing AI editors (Claude Desktop, Cursor, VSCode) to read the Sovereign Markdown Palace and OpenWiki knowledge graph locally without pasting context.
To configure your AI client, point it to our uv-managed server script:
{
"mcpServers": {
"dsom-palace": {
"command": "uv",
"args": ["run", "tools/mcp/server.py"]
}
}
}
Entry Point 4: Subagent Orchestration Workflow
If you are scaling complex engineering tasks using autonomous AI subagents.
Read This First: governance/MULTI-AGENT-PROTOCOLS.md
7. The Procedural Skill Entry Point (AI Automation)
If you need to teach your AI how to perform repetitive operational workflows.
Read This First: governance/AI-SKILL-ARCHITECTURE.md and governance/AI-SLASH-COMMANDS-GUIDE.md
8. The Sovereign Knowledge Entry Point (LLM WIKI Adoption)
If you are migrating legacy documentation into an AI-native memory palace.
Read This First: governance/LLM-WIKI-ADOPTION.md
9. The Security & Defense Entry Point (Defensive GitOps)
If you are adopting DSOM for secure infrastructure or production environments.
Read This First: governance/GITOPS-AIOPS-ANSIBLE-STRATEGY.md
10. The Token Performance Entry Point (Context Efficiency)
If you are onboarding a new AI agent or bootstrapping a new project and want to ensure token-efficient LLM operation from day one.
Read This First: governance/DSOM-TOKEN-PERFORMANCE-PLAYBOOK.md
11. The Discovery Entry Point (Knowledge-First Protocol)
If you are an AI agent or human operator attempting to execute an exploratory terminal command or probe external nodes.
Read This First: governance/SOP-KNOWLEDGE-FIRST-DISCOVERY.md
12. The Initialisation Entry Point (Mechanical Boot Sequence)
If you need to understand how the AI's cognitive engine boots up, reanimates, and establishes its laws before the first prompt is processed.
Read This First: governance/AI-INITIALIZATION-SEQUENCE.md
13. The Automated State Sync Entry Point (Semantic Compaction)
If you need to understand how DSOM manages token bloat automatically across Pull Requests.
Read This First: governance/DSOM-AUTOMATED-STATE-SYNC.md
14. The Cognitive Architecture Entry Point (The Tri-Phasic Mind)
If you need to understand how the AI's cognitive pipeline is split into Active, Twilight, and Deep states.
Read This First: governance/DSOM-TRI-PHASIC-COGNITIVE-ARCHITECTURE.md
15. The Native OpenWiki Knowledge Graph Entry Point (Zero-Binary Architecture)
If you want to maintain a high-density, zero-binary knowledge graph across your repository.
Read This First: tools/HOWTO-OPENWIKI.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/tools/HOWTO-OPENWIKI/) and governance/OPENWIKI-INTEGRATION-GUIDE.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/governance/OPENWIKI-INTEGRATION-GUIDE/)
16. The Legal & Disclaimer Entry Point (Risk Governance)
If you want to review the privacy statement, cost and design assumptions, or liability disclaimers for this repository.
Read This First: LEGAL-NOTICE.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/LEGAL-NOTICE/)
17. The Open Knowledge Format (OKF) Entry Point (Foundational Context Engine)
If you are adopting OKF v0.1/v0.2 to structure your repository's documentation and memory assets for maximum AI token efficiency and zero context loss.
Read This First: OKF-ADOPTION-GUIDE.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/OKF-ADOPTION-GUIDE/)
Why it matters: OKF is Google Cloud's vendor-neutral specification that powers DSOM's spatial memory architecture (.agents/brain/ and .agents/skills/). It achieves 98%+ token compression, enables progressive disclosure directory routing, and preserves persistent memory across AI agent reboots.
[!IMPORTANT] Adoption & Migration Rule for Downstream Projects: Adopt OKF v0.2 as soon as possible to incorporate trust signals (
sources,generated,verified,status,stale_after). To prevent context window inflation and token waste, do not execute drastic, mass full-corpus rewrites. Instead, migrate existing files to OKF v0.2 opportunistically only when actively editing or updating a document.
18. The AI Guardrails & Custom Validators Entry Point (Defense-in-Depth Safety)
If you want to understand, configure, or develop deterministic and LLM-powered guardrails (combining Guardrails AI and DSOM Native runtime).
Read This First: governance/AI-GUARDRAILS-MASTER-GUIDE.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/governance/AI-GUARDRAILS-MASTER-GUIDE/)
Why it matters: Autonomous agents must operate within deterministic boundaries. DSOM enforces a Tri-Phasic guardrail pipeline: Active FastMCP tool argument validation, Twilight State AST/regex command interception (blocking raw pip and credential leaks), and Deep State automated pytest gates.
19. The Episodic Record & State Anchor Entry Point (Zero Context Amnesia)
If you need to understand how the AI maintains unbroken mental state across chat reboots and platform boundaries via episodic serialisation.
Read This First: DSOM-EPISODIC-RECORD-TEMPLATE.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/DSOM-EPISODIC-RECORD-TEMPLATE/)
Why it matters: Enforces Rule 18 (The Episodic Resume Protocol). At the end of every major workflow or session handover, the AI outputs a strictly formatted [DSOM EPISODIC RECORD] block containing timestamps, test counts, Git commits, and mental anchors, enabling zero-loss resume across Google Jules, Cursor, Claude Desktop, and Gemini.
20. The Agent Plugins 1.0.0 Packaging Entry Point (Universal Interoperability)
If you want to package, distribute, or install DSOM Agent Skills and FastMCP servers into portable, client-agnostic packages across Google Antigravity, Jules, Cursor, Claude Code, and Codex.
Read This First: governance/DSOM-AGENT-PLUGINS-SPECIFICATION.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/governance/DSOM-AGENT-PLUGINS-SPECIFICATION/)
Why it matters: Backed by Google, Amazon, Microsoft, OpenAI, Cursor, and Vercel, the Agent Plugins 1.0.0 directory standard (agent-plugins.org/specification) provides a single closed manifest (plugin.json), explicit MCP descriptors (mcp.json), and fixed skills/ folders, eliminating packaging friction and drift across all modern AI coding agents.
21. The Mintlify One-Way Docs Sync Entry Point (Knowledge Brain Publishing)
If you want to publish sovereign documentation from docs-source/ to a downstream Mintlify docs repository (linuxmalaysia/my-knowledge-brain) serving harisfazillah.mintlify.site.
Read This First: governance/MINTLIFY-ONE-WAY-SYNC-PIPELINE.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/governance/MINTLIFY-ONE-WAY-SYNC-PIPELINE/ | Live Portal: https://harisfazillah.mintlify.site)
Why it matters: Enforces Rule 31 (Mintlify One-Way Docs Sync & Safety Guards). A deterministic one-way sync pipeline protected by 5 strict safety guards (A–E) ensuring an empty or half-populated source can never destroy the downstream Mintlify docs repo.
22. The Mintlify User Manual & Downstream Project Prompt Entry Point (Reusable Architecture)
If you want to adopt the Mintlify User Manual compilation architecture, copy the universal agent prompt, or scaffold user/admin/developer manuals into any new project.
Read This First: governance/MINTLIFY-USER-MANUAL-SYNC-GUIDE.md (Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/governance/MINTLIFY-USER-MANUAL-SYNC-GUIDE/)
Why it matters: Provides the drop-in AI agent prompt, 3-manual stratification model (User/Admin/Developer), and scripts for bootstrapping Mintlify documentation pipelines across external projects.
Deep State of Mind (DSOM) For My AI Protocol | Harisfazillah Jamel (LinuxMalaysia) | 2026-08-23 Standard: UK English | DBP-standard Bahasa Melayu Malaysia (Piawai) | GNU General Public License v3.0