> ## Documentation Index
> Fetch the complete documentation index at: https://harisfazillah.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# DSOM Quick Start: From Clone to Cognitive Handshake

> Set up the Deep State of Mind framework, initialise your AI brain, fill in your Project Identity Card, and perform the first Cognitive Handshake.

Getting a new project running under DSOM takes about fifteen minutes. You clone the template skeleton, initialise the AI brain directory, fill in your project's identity details, run a pre-flight audit, generate a context manifest, and then hand that manifest to your AI with a single handshake phrase. After step six, your AI knows your environment, your security doctrine, your Git conventions, and exactly where you left off — and it will remember all of that every time you start a new session.

<Steps>
  ### Clone and Reset

  Clone the DSOM skeleton repository, then immediately run the template-reset script to clear the framework author's Git history and brain files so you start with a clean slate.

  ```bash theme={null}
  # Clone the DSOM skeleton into your new project directory
  git clone https://github.com/linuxmalaysia/deep-state-of-mind-for-my-ai.git my-new-project
  cd my-new-project

  # Clear the old Git history and brain artifacts for your fresh project
  bash tools/template-reset.sh
  ```

  <Tip>
    If you are migrating an existing DSOM project rather than starting from scratch, follow the [DSOM Project Cloning Guide](https://github.com/linuxmalaysia/deep-state-of-mind-for-my-ai/blob/main/docs/HOWTO-CLONE-DSOM-PROJECT.md) instead to preserve all cognitive capabilities during the transfer.
  </Tip>

  ### Initialise the Brain

  Run the brain initialisation script for your platform. This creates the `.agents/brain/` directory and seeds it with the four core artifacts your AI will read at the start of every session.

  <CodeGroup>
    ```bash Linux / WSL2 theme={null}
    bash tools/init-brain.sh
    chmod +x tools/*.sh
    ```

    ```powershell Windows (PowerShell) theme={null}
    .\tools\init-brain.ps1
    ```
  </CodeGroup>

  After the script completes, your `.agents/brain/` directory contains four files:

  | File                     | Purpose                                                              |
  | :----------------------- | :------------------------------------------------------------------- |
  | `task.md`                | **Present** — The AI's active checklist; what to work on right now   |
  | `walkthrough.md`         | **Past** — Session history log and Mental Anchors                    |
  | `implementation_plan.md` | **Future** — Your project roadmap and phase targets                  |
  | `DSOM_TEMPLATE.md`       | **Template** — A blank walkthrough structure for new session entries |

  ### Fill in Your Project Identity Card

  The `docs/governance/AI-COGNITIVE-TWIN-PROTOCOL.md` file is the most important file in the entire framework. It is your **Project Identity Card** — the document that tells the AI who you are, what your environment looks like, and how it must behave. Open it and replace every `[PLACEHOLDER]` with your real project details.

  ```bash theme={null}
  nano docs/governance/AI-COGNITIVE-TWIN-PROTOCOL.md
  ```

  Work through these four sections carefully:

  | Section                    | What to Fill In                                                                                                         | Example                                                               |
  | :------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
  | **Project Name**           | `[YOUR_PROJECT_NAME]`                                                                                                   | `my-kafka-pipeline`                                                   |
  | **4-Tier Environment Map** | T1 = Command Centre path (Windows/Mac), T2 = Dev Bridge (WSL2/VM), T3/T4 = Production host, user, UID, and working path | T1: `C:\Projects\kafka`, T3: `prod-node-01`, user `kafka`, UID `1001` |
  | **Security Doctrine**      | Who runs as root vs. which UID your application processes use                                                           | `App runs as UID 1001; Ansible connects as deploy user`               |
  | **Mental Anchor §8**       | Set to `"Fresh project. Phase 1 pending."` for a brand-new project                                                      | `Fresh project. Phase 1 pending.`                                     |

  <Warning>
    The AI will not operate correctly until every `[PLACEHOLDER]` in `docs/governance/AI-COGNITIVE-TWIN-PROTOCOL.md` is filled in. The `audit-pre-flight.sh` script in the next step will explicitly flag any unfilled values and block you from proceeding.
  </Warning>

  ### Run the Pre-Flight Audit

  <Note>
    **Infrastructure projects only:** If your project uses Ansible to manage remote nodes, complete the Ansible baseline setup before running the audit. Follow `docs/HOWTO-SETUP-ANSIBLE-BASELINE.md` inside the cloned repository, then verify connectivity with `ansible all -m ping -i inventory/hosts.yml`. The pre-flight audit will check for `inventory/hosts.yml` and warn if it is missing.
  </Note>

  Run the pre-flight audit to verify that your brain artifacts are in place, your Git repository is synchronised, and your Project Identity Card contains no unfilled placeholders.

  <CodeGroup>
    ```bash Linux / WSL2 theme={null}
    ./tools/audit-pre-flight.sh
    ```

    ```powershell Windows (PowerShell) theme={null}
    .\tools\audit-pre-flight.ps1
    ```
  </CodeGroup>

  Every check should report `[PASS]` or `[OK]`. If you see any `[FAIL]` entries, fix the underlying issue before moving to the next step — a failed audit means the AI will receive incomplete or incorrect context during the Cognitive Handshake.

  ### Generate the Context Manifest

  Run the reanimate script to bundle all your brain artifacts, your Project Identity Card, and your Palace Registry into a single context manifest file that you will upload to your AI.

  <CodeGroup>
    ```bash Linux / WSL2 theme={null}
    bash tools/reanimate.sh
    ```

    ```powershell Windows (PowerShell) theme={null}
    .\tools\reanimate.ps1
    ```
  </CodeGroup>

  The script outputs a file named `sod_manifest_YYYY-MM-DD.txt` in your project root. This manifest is the complete cognitive snapshot of your project — everything the AI needs to resume as your Cognitive Digital Twin without you having to re-explain anything.

  <Tip>
    Before uploading the manifest to an external AI service, run `./tools/privacy-guardian.sh` to scan for any leaked IP addresses, API keys, tokens, or internal paths that should not leave your machine.
  </Tip>

  ### Perform the Cognitive Handshake

  Upload the generated `sod_manifest_YYYY-MM-DD.txt` to your AI (as a file attachment or by pasting its contents), then send the following handshake phrase exactly as written:

  ```text theme={null}
  Initialise DSOM Protocol. Read the uploaded manifest. Summarise the current
  Mental Anchor and confirm the 4-Tier environment map from the
  AI-COGNITIVE-TWIN-PROTOCOL.md section. State: 'Sovereign State Synchronised'
  when ready.
  ```

  Wait for the AI to respond with **"Sovereign State Synchronised"** before issuing any project instructions.
</Steps>

<Note>
  Once your AI confirms **"Sovereign State Synchronised"**, it has loaded your complete project context. It now knows your 4-Tier environment map (T1 → T4), your security doctrine (who runs as root and which UID your applications use), your Git commit convention, and the current Mental Anchor — the exact logical point where your last session ended. Every subsequent prompt in this session builds on that shared understanding without any re-explanation.
</Note>


## Related topics

- [[AGENT] DSOM Cognitive Digital Twin: Project Operational Protocol (v2.0)](/governance/ai-cognitive-twin-protocol.md)
- [🌅 SOD-RITUAL.md - Start-of-Day Ritual](/rituals/start-of-day.md)
- [📖 DSOM Operational Guide (Level 3 - Specialised Tasks)](/governance/operational-guide.md)
- [🧠 Deep State of Mind (DSOM) For My AI Protocol](/core-concepts.md)
- [DSOM - Deep State of Mind: AI Governance Framework](/index.md)