Obsidian Setup — ora-ai.app

PURPOSE

This framework sets up an Obsidian vault integrated with the reader’s local AI system. It handles two scenarios: creating a new vault for users who don’t use Obsidian, or integrating starter files into an existing vault for users who already do. The framework installs minimal frontmatter conventions and starter templates without imposing a comprehensive vault architecture — the full knowledge architecture is covered in Part V of the book.

INPUT CONTRACT

Required:

This framework loaded into the local AI system. Source: user tells the AI to read and execute this file, or follows instructions in Chapter 13.
The workspace directory structure from the first boot framework. Source: [workspace]/ with knowledge/ and logs/ directories present.

Optional:

Existing vault path: User has an Obsidian vault they want to integrate. Source: user provides the path during execution. Default if absent: framework creates a new vault.
Starter files from the book repository: Templates and guides at [workspace]/frameworks/book/obsidian/. Source: cloned by the first boot framework. Default if absent: framework generates starter files directly.

OUTPUT CONTRACT

Primary outputs:

A configured Obsidian vault with minimal frontmatter conventions (type and date created fields) and starter templates installed. Quality threshold: the vault opens in Obsidian without errors, contains at least one template file, and the frontmatter convention is documented in a starter guide within the vault.

Secondary outputs:

Updated orchestrator configuration noting the vault location (if different from the default knowledge/ directory).
A brief “Welcome to Your Vault” note explaining what was set up and how to use it.

EXECUTION TIER

Agent: This framework executes through the local orchestrator with tool access. It uses file_read and file_write to create vault files, and browser_open to download Obsidian if needed. The local AI guides the user conversationally.

EVALUATION CRITERIA

Vault Functionality: The vault opens in Obsidian without errors and displays the installed files correctly.
- 5: Vault opens cleanly. All installed files visible with correct frontmatter. Templates accessible from Obsidian’s template inserter.
- 4: Vault opens cleanly. All files present. Minor issue (e.g., template folder not configured in Obsidian settings — requires manual step).
- 3: Vault opens. Files present. One file has a formatting issue that does not affect functionality.
- 2: Vault opens but some installed files are missing or have broken frontmatter.
- 1: Vault cannot be opened, or no files were installed.
Frontmatter Convention Clarity: The minimal frontmatter convention is documented clearly enough that the user can create new notes following it without consulting the framework again.
- 5: Starter guide explains the convention with examples. Template files demonstrate correct usage. User can follow the convention from the guide alone.
- 4: Convention documented and demonstrated. One minor ambiguity in the guide.
- 3: Convention documented. Examples present but could be clearer.
- 2: Convention mentioned but not clearly explained or demonstrated.
- 1: No documentation of the frontmatter convention.
Non-Destructive Integration: For existing vault users, no existing files are modified, moved, or deleted.
- 5: All starter files placed in a clearly identified location. No existing files touched. User informed exactly what was added and where.
- 4: All starter files placed correctly. One file created in a location that might overlap with user’s existing organization (but no overwrites).
- 3: Starter files installed. No overwrites occurred. Location could be better isolated.
- 2: One existing file was unintentionally modified (e.g., settings file updated without asking).
- 1: Existing files deleted or overwritten.

NAMED FAILURE MODES

The Architecture Imposition Trap: The framework installs an elaborate vault structure (dozens of folders, complex property schemas, rigid organizational rules) that overwhelms the user and conflicts with their existing habits. Correction: Install only the minimal convention (type and date created frontmatter) and starter templates. The full knowledge architecture is aspirational content in Part V. The user adopts additional structure when they understand why.

The Settings Overwrite Trap: For existing vault users, the framework modifies Obsidian’s .obsidian/ settings directory, changing the user’s themes, plugins, or hotkeys. Correction: Never modify anything in the .obsidian/ directory. The only files this framework creates are Markdown notes and a templates folder (if the user approves).

The Path Assumption Trap: The framework assumes the vault is at the default workspace knowledge/ directory, but the user’s vault is elsewhere. Correction: Always ask for the vault location. Offer the default as a suggestion, not an assumption. Update the orchestrator’s knowledge path configuration if the vault is elsewhere.

The Obsidian Not Installed Trap: The user wants to set up a vault but hasn’t installed Obsidian yet. Correction: Check whether Obsidian is installed. IF not, THEN guide the user through downloading and installing it before proceeding with vault setup.

The Template Folder Conflict Trap: The user’s existing vault already has a Templates folder with their own templates. The framework creates new templates that mix with or displace the user’s templates. Correction: Place book-provided templates in a clearly namespaced subfolder (Templates/book/ or similar). Never place files directly in the user’s existing template root.

The Sync Conflict Trap: The user syncs their vault via iCloud, Dropbox, or Obsidian Sync, and the framework creates files that trigger merge conflicts. Correction: All files created by this framework are new additions (not modifications of existing files). New file creation does not cause sync conflicts. Warn the user that Obsidian Sync may take a moment to propagate new files across devices.

LAYER 1: SCENARIO DETECTION

Stage Focus: Determine whether the user has an existing Obsidian vault or needs a new one, and whether Obsidian itself is installed.

Processing Instructions

Ask the user:

OBSIDIAN SETUP

Obsidian is a note-taking application that your AI system can write
to directly. It provides a human-friendly way to browse, search, and
edit the knowledge your AI generates.

Which best describes your situation?

A) I don't use Obsidian — set everything up for me
B) I use Obsidian and want to integrate it with my AI system
C) I've heard of Obsidian but want to understand it before deciding
D) Skip — I'll use the plain knowledge/ directory for now

IF option A:
- Check whether Obsidian is installed (look for the application in standard locations).
- IF not installed: proceed to Layer 2 (Installation).
- IF installed: proceed to Layer 3 (New Vault Creation).
IF option B:
- Ask: “What is the path to your Obsidian vault? (This is the folder that contains the .obsidian/ hidden directory.)”
- Verify the path exists and contains an .obsidian/ directory.
- IF valid vault: proceed to Layer 4 (Existing Vault Integration).
- IF path invalid or no .obsidian/ found: “That doesn’t appear to be an Obsidian vault. Would you like me to check a different path, or create a new vault?”
IF option C:
- Provide a brief explanation: “Obsidian is a free application that displays Markdown files as an interconnected knowledge base. Your AI system already saves files as Markdown — Obsidian just makes them browsable and searchable with a visual interface. It runs entirely on your machine. Files are plain Markdown — if you stop using Obsidian, your files are still readable by any text editor. There’s no lock-in.”
- After explanation, ask whether to proceed with setup or skip.
IF option D:
- Record that the user is using the plain directory structure.
- Confirm: “Your AI system will use the knowledge/ directory at [workspace]/knowledge/ for file storage. You can set up Obsidian later by running this framework again.”
- Skip to Layer 6 (Summary) with minimal output.

LAYER 2: OBSIDIAN INSTALLATION (if needed)

Stage Focus: Guide the user through downloading and installing Obsidian.

Processing Instructions

Determine the download URL:
- macOS: https://obsidian.md/download
- Linux: https://obsidian.md/download (AppImage, Snap, or Flatpak)
- Windows: https://obsidian.md/download

Open the download page in the user’s browser:

<tool_call>
<n>browser_open</n>
<url>https://obsidian.md/download</url>
</tool_call>

Instruct the user: “I’ve opened the Obsidian download page. Download and install the version for your operating system. Obsidian is free for personal use. When the installation is complete, tell me and we’ll continue.”
Wait for user confirmation.
Verify installation by checking for the Obsidian application in standard locations:
- macOS: /Applications/Obsidian.app
- Linux: check which obsidian or look in common application directories
- Windows: check Program Files and AppData for Obsidian
IF verification succeeds: proceed to Layer 3.
IF verification fails but user confirms installation: proceed to Layer 3 (the application may be installed in a non-standard location).

LAYER 3: NEW VAULT CREATION

Stage Focus: Create a new Obsidian vault integrated with the AI workspace.

Processing Instructions

Determine the vault location. Offer the user a choice:

Where would you like your knowledge vault?

A) Inside my AI workspace (recommended for new users)
   Location: [workspace]/knowledge/
   This keeps everything together.

B) A separate location
   You specify the path. Your AI system will be configured
   to read and write files there.

IF option A: The vault location is [workspace]/knowledge/. This directory already exists from the first boot framework. Create the .obsidian/ directory inside it to initialize it as a vault.
IF option B: Record the user-specified path. Create the directory if it does not exist. Create the .obsidian/ directory inside it. Update the orchestrator’s knowledge path:

Write to [workspace]/config/knowledge-path.json:
```
{
  "vault_path": "[user-specified path]",
  "updated": "[ISO date]"
}
```
Create the minimal .obsidian/ configuration:
- Create [vault]/.obsidian/app.json with default settings (empty object or minimal defaults).
- Do NOT install themes, plugins, or custom CSS. The user’s preferences are their own.
Proceed to Layer 5 (Starter Files).

LAYER 4: EXISTING VAULT INTEGRATION

Stage Focus: Add starter files to an existing vault without modifying any existing content.

Processing Instructions

Confirm the vault path. List the top-level contents of the vault to orient the framework.
Check for existing templates:
- IF a Templates/ folder exists: note it. Starter templates will go in Templates/book/.
- IF no Templates/ folder exists: starter templates will go in Templates/book/.

Inform the user what will be created:

I'll add the following to your vault at [path]:

- Templates/book/     — Two template files for AI-generated notes
- _Book Starter/      — A welcome guide and frontmatter reference

I will NOT modify any of your existing files, settings, themes,
or plugins. Everything I add is in new folders that don't overlap
with your current vault structure.

Proceed?

Wait for user confirmation.
IF the vault is not at [workspace]/knowledge/, THEN update the orchestrator’s knowledge path (same as Layer 3, step 3).
Proceed to Layer 5 (Starter Files).

LAYER 5: STARTER FILES

Stage Focus: Install the minimal frontmatter convention and starter templates.

Processing Instructions

Check the book repository for starter files:
- IF [workspace]/frameworks/book/obsidian/ exists and contains files, THEN copy those files to the vault.
- IF the repository is not available, THEN generate the files directly (content specified below).

Create the template files:

Create [vault]/Templates/book/AI Note Template.md:

---
type: {{type}}
date created: {{date}}
---

# {{title}}

Create [vault]/Templates/book/AI Engram Template.md:

---
type: engram
date created: {{date}}
---

# {{title}}

## Key Idea



## Supporting Evidence



## Open Questions

Create the welcome guide:

Create [vault]/_Book Starter/Welcome to Your Vault.md:

---
type: engram
date created: [today's date]
---

# Welcome to Your Vault

Your AI system can now write directly to this vault. When it generates
notes, summaries, or knowledge artifacts, they appear here as Markdown
files that Obsidian renders and connects.

## The Minimal Convention

Every file your AI creates includes two frontmatter fields:

- **type** — What kind of note this is (engram, resource, working, etc.)
- **date created** — When it was created

That's it for now. These two fields let your system organize and
retrieve notes effectively. A richer property schema is available
in Part V of the book if you want it later.

## How Your AI Writes to the Vault

Your AI uses the file_write tool to create Markdown files in this
directory. Obsidian detects new files automatically — you don't need
to refresh or import anything.

## What's Here

- **Templates/book/** — Two templates for AI-generated notes.
  You can use these with Obsidian's template inserter, or your
  AI can use them as formatting guides.

- **This folder (_Book Starter/)** — Reference materials from
  the book's setup process. You can move or delete this folder
  whenever you like.

## Next Steps

- Start using your AI system normally. When it produces useful
  output, ask it to save the output to your vault.
- Browse the knowledge/ directory to see what accumulates.
- When you're ready for a deeper knowledge architecture, Part V
  of the book covers the full system: note types, provenance,
  ChromaDB vector search, and the Knowledge Artifact Coach.

Create the frontmatter reference:

Create [vault]/_Book Starter/Frontmatter Reference.md:

---
type: engram
date created: [today's date]
---

# Frontmatter Reference

## Required Fields (Minimal Convention)

Every note in this vault should have YAML frontmatter at the top
of the file, between triple-dash markers:

```yaml
---
type: [note type]
date created: [YYYY/MM/DD]
---

Type

The structural role of this note. Common values:

engram — Synthesized knowledge. Your own understanding, analysis, or conclusions. Highest trust level for retrieval.
resource — External information. Articles, references, quotes, data. Useful but not your own synthesis.
working — Work in progress. Drafts, scratch notes, incomplete thinking. Lowest retrieval priority.
chat — Saved conversation excerpts. Time-decaying retrieval priority.

You can use any value. These four cover most needs.

Date Created

The date this note was created, in YYYY/MM/DD format. Auto-populated by templates.

Optional Fields (Available Later)

Part V of the book introduces additional fields for readers who want a richer knowledge architecture:

nexus — Which project or passion this note serves
writing — Fiction/book production classification
hub — Priority value for navigational hub notes

These are optional. The minimal convention (type + date created) is sufficient for the AI system to organize and retrieve notes.


5. **Verify all files were created:**
- List the contents of the Templates/book/ directory. Confirm both templates are present.
- List the contents of the _Book Starter/ directory. Confirm both guides are present.
- Verify each file has valid YAML frontmatter by reading the first few lines.

---

## LAYER 6: SUMMARY

**Stage Focus:** Confirm setup and explain what comes next.

### Processing Instructions

1. **IF vault was set up (new or existing):**

OBSIDIAN VAULT CONFIGURED

Vault location: [path] Files installed:

Templates/book/AI Note Template.md
Templates/book/AI Engram Template.md
_Book Starter/Welcome to Your Vault.md
_Book Starter/Frontmatter Reference.md

Your AI system is configured to write to this vault. Open Obsidian and select this vault to browse the files.

[IF vault location differs from workspace/knowledge/:] Your AI system has been configured to use [path] as its knowledge directory. Files saved by the AI will appear in your vault.

The full knowledge architecture (note types, provenance hierarchy, ChromaDB vector search, and the Knowledge Artifact Coach) is covered in Part V of the book. For now, the minimal convention (type and date created) is all you need.


2. **IF user chose to skip:**

Obsidian setup skipped. Your AI system uses the plain directory at [workspace]/knowledge/ for file storage. You can set up Obsidian at any time by telling your AI: “Read and execute frameworks/obsidian-setup.md”


---

## RECOVERY

### Obsidian Cannot Open the Vault

WHEN Obsidian reports an error opening the vault:
- Check whether the `.obsidian/` directory exists and contains `app.json`.
- IF missing: recreate the `.obsidian/` directory and `app.json`.
- IF present: the error is likely an Obsidian version issue. Suggest updating Obsidian.

### Vault Location Change

WHEN the user wants to move their vault after setup:
- Update `[workspace]/config/knowledge-path.json` with the new path.
- Inform the user: "Move the vault folder to the new location using your file manager (not through the AI system). Then tell me the new path and I'll update the configuration."

### Files Not Appearing in Obsidian

WHEN the user reports that AI-created files don't appear in Obsidian:
- Verify the file_write tool is targeting the correct directory (the vault path, not the default workspace/knowledge/ if they differ).
- Check that the files have the `.md` extension.
- Suggest: "Try clicking in Obsidian's file explorer and pressing Ctrl+R (or Cmd+R on Mac) to refresh."

---

## EXECUTION COMMANDS

1. Confirm you have fully processed this framework.
2. Begin with Layer 1 (Scenario Detection).
3. Follow the routing determined by the user's response through the appropriate layers.
4. Complete Layer 6 (Summary) for all paths.
5. This framework is optional. IF the user expresses disinterest at any point, THEN gracefully exit with the skip path from Layer 1, option D.

---

*End of Obsidian Setup Framework v1.0*