---

updated: 2026-08-13

🧠 loey_space — Personal Knowledge Management & Second Brain Architecture

A modular, automated, and secure Personal Knowledge Management (PKM) system built inside Obsidian. Engineered around the PARA/MOC methodology, real-time 2-way habit tracking, automated multi-domain AI enrichment, and a unified #0C0D13 ultra-dark command center interface.

---

📚 Table of Contents

• ⚡ Quickstart
• 🖼️ Screenshots
• ✨ Main Features
• ⚡ HomePulse Command Center
• 🗂️ Vault Directory Architecture
• 📖 Documentation
• 🛠️ Installation & Setup Guide
• 💡 Daily Workflows & Keyboard Shortcuts
• 📱 Mobile Workflow
• 📊 Habit Analytics
• 📋 Task System Rules & Conventions
• 🎨 Styling & Aesthetics
• 🔒 Security & Git Safety
• 🧯 Troubleshooting
• 🤝 Contributing

---

⚡ Quickstart

Five minutes from clone to a working dashboard:

1. Clone and open — git clone https://github.com/lowqualityloey/loey_space.git, then in Obsidian choose Open folder as vault.
2. Leave Restricted Mode — Settings → Community plugins → Turn on community plugins. Nothing loads until you do.
3. Turn auto-updates off — Settings → Community plugins → Auto-update plugins: OFF. Two plugins here are local custom builds and an update replaces them.
4. Add an API key (optional) — cp .env.example .env, then paste a key from Google AI Studio into GEMINI_API_KEY. Everything except AI enrichment works without one.
5. Start today — Ctrl + P → HomePulse: Open Dashboard View, then Ctrl + P → QuickAdd: Create Daily Note.

That's it. Habit tracking, task dashboards and the MOC queries all come alive as soon as a daily note exists.

[!IMPORTANT] Two things that will bite a fresh clone:

1. homepulse and kanban-status-sync are bundled custom builds in .obsidian/plugins/. Do not install or update them from the Community Store — HomePulse would be replaced by stock code, and Kanban Status Sync isn't published there at all. Keep Auto-update plugins: OFF.
2. Secrets live only in .env, which is git-ignored. Copy .env.example, never commit real keys, and read the Vault Security Policy.

---

🖼️ Screenshots

⚡ HomePulse Command Center

The custom HomePulse plugin: habits sync two ways with today's daily note, open tasks aggregate from daily notes and project kanbans, and Execution Pulse tracks focus minutes, note rhythm and completion ratios live.

📅 Daily Note

One note per day carrying mood / energy / sleep_hours, habits, a timestamped log, and an AI Daily Summary generated from what was actually logged. Unfinished tasks roll forward automatically; the previous day marks its copies [>] so nothing is counted twice.

🚀 Project Kanban

Each project gets a board. Card checkboxes follow their lane automatically — To Do is [ ], In Progress is [/], Done is [x] with a completion date — and ticking a card anywhere moves it to Done. Backlog and Archive stay out of the task dashboards.

---

✨ Main Features

Feature	Description
HomePulse Dashboard	Custom native plugin with real-time widgets — habits, tasks, pomodoro, focus, projects, tech tree, activity heatmap, all in one view
2-Way Habit Sync	Toggle habits in the dashboard and they instantly update in today's daily note (and vice versa)
Multi-Domain AI Enrichment	One shortcut (Ctrl+Shift+A) analyzes any note — generates summaries for daily notes, explanations for concepts, code breakdowns for dev notes
Weekly AI Summaries	Automated 7-day analysis of mood, energy, tasks, and habits with actionable recommendations
Habit Analytics Dashboard	30-day rolling metrics, streak tracking, day-of-week patterns, and improvement recommendations
Smart Task Management	Tasks live in daily notes and project kanbans, aggregated in real-time via _Tasks MOC.md with status indicators ([ ], [/], [x])
Project Kanban Integration	Each project gets a visual kanban board; tasks from To Do/In Progress/Review flow into the central task hub (Backlog excluded)
GitHub Project Sync	Bi-directional 2-way sync between Obsidian Kanbans and GitHub Projects v2 (github_project_number) via QuickAdd & gh CLI
Kanban Status Sync	Drag a card between lanes and its checkbox follows automatically — To Do [ ], In Progress [/], Done [x] with a completion date
Mobile Quick Capture	4 mobile-optimized commands for instant capture on the go — process later on desktop
Inbox Auto-Classification	Quick captures tagged with type/area/priority suggestions based on content analysis
Token Triage Sweep	Tag a capture line #do / #dev / #concept / #learn / #ref / #personal / #project / #bin, then file the whole inbox in one pass — swept lines are logged, never silently deleted
Dynamic Tech Tree	Auto-generated capability map scanning projects, concepts, and resources across the vault
Execution Pulse	Live productivity analytics — habit %, focus minutes, note rhythm, task completion ratios
PARA/MOC Architecture	Clean folder separation with Maps of Content for navigation — scales without friction
Ultra-Dark Command Center	Glassmorphic #0C0D13 theme with JetBrains Mono, Inter, and custom CSS snippets

---

⚡ HomePulse Command Center

The heart of loey_space is HomePulse (.obsidian/plugins/homepulse), a high-performance native dashboard plugin:

• 🔄 2-Way Real-Time Habit Sync: Toggling habit checkboxes inside the Habits widget instantly updates - [ ] / - [x] in today's active daily note (01-Daily/YYYY-MM-DD.md) and 99-Templates/Daily.md.
• ⚡ Execution Pulse: Live productivity analytics tracking daily habit completion percentage, focus/pomodoro minutes, 7-day note creation rhythm, and task completion ratios.
• 📊 Knowledge Profile: Real-time vault metric counter displaying total Notes, Areas, Projects, and Tags.
• 🎯 Today's Focus: Editable focus widget that live-syncs with your daily note's Focus section (supports multiple focus items).
• 🛠️ System Quick Actions: 1-click execution shortcuts for timestamped daily note generation, quick capture, new projects, and dev snippets.
• 📌 Open Tasks Widget: Live active task feed with Lucide status icons — In Progress tasks sorted to top, Backlog/Archive excluded.
• 🌳 Tech Tree: Dynamic capability map auto-generated from your vault's projects, concepts, and resources.
• 📅 Activity History: GitHub-style contribution heatmap showing your vault activity over the year.

---

🗂️ Vault Directory Architecture

loey_space/
├── Home.md                      # Central Command Dashboard (Navigation, Active Tasks, Projects, Inbox)
├── 00-Inbox/                    # Quick capture dump & triage
│   ├── _Inbox MOC.md            # Unprocessed notes dashboard
│   └── _Triage MOC.md           # Stale notes & overdue reviews
├── 01-Daily/                    # Daily logs, habits, energy/sleep tracking, AI reflections
│   ├── _Daily MOC.md            # Daily notes navigation & monthly overview
│   ├── _Tasks MOC.md            # Task command center, in-progress, completion history & analytics
│   └── Habit Analytics Dashboard.md  # 30-day habit metrics, streaks, trends
├── 02-Projects/                 # Active development projects & build specifications
│   ├── _Projects MOC.md         # Project dashboard with progress bars
│   └── weather-dashboard/       # Example project (notes + Kanban board)
├── 03-Dev/                      # Code snippets, technical patterns, debugging notes
├── 04-Learning/                 # Courses, tutorials, & study notes
├── 05-Personal/                 # Personal goals, life & fitness logs
├── 06-Resources/                # Technical documentation, API specs, & system scripts
│   ├── APIs/                    # API specs & integration documentation
│   ├── scripts/                 # Automation (AI enricher, triage-sweep, inbox-status, weekly summary)
│   ├── Mobile Workflow Guide.md # Mobile capture setup & usage
│   ├── Second Brain Guide.md    # System usage, folder guidelines & workflow rules
│   └── Vault Security Policy.md # Secret management & Git safety rules
├── 07-Reviews/                  # Weekly & Monthly retrospectives (AI-generated)
├── 08-Concepts/                 # Evergreen technical & domain concepts
├── 99-Attachments/              # Monthly subfolders (YYYY-MM/) for screenshots and media
├── 99-Templates/                # Master Templater & QuickAdd note blueprints
│   ├── Daily.md                 # Daily note template (habits, tasks, reflections)
│   ├── Mobile Capture.md        # Mobile quick capture template
│   ├── Mobile Task.md           # Mobile task capture template
│   └── Mobile Idea.md           # Mobile idea capture template
├── .obsidian/                   # Vault configuration, custom plugins, snippets & themes
│   ├── plugins/homepulse/       # Custom HomePulse dashboard plugin
│   ├── plugins/kanban-status-sync/  # Syncs kanban card checkboxes to their lane
│   └── snippets/                # CSS snippets (dashboard-cards, fonts, project-tasks, homepulse-mobile)
├── .kiro/                       # Kiro IDE hooks (env validation, git safety, triage suggestions)
├── .secrets/                    # [GIT-IGNORED] Private human-readable sensitive notes
└── .env                         # [GIT-IGNORED] Real API keys and machine credentials

---

📖 Documentation

Full reference lives inside the vault rather than a separate docs/ tree, so every guide stays searchable, linkable and enrichable in Obsidian:

Guide	Covers
CONTRIBUTING	Open/closed scope, testing without Obsidian, PR workflow, security rules
Second Brain Guide	Folder architecture, QuickAdd flows, the AI enricher contract, triage tokens, task rules, daily routine
Mobile Workflow Guide	Mobile toolbar setup and the capture-fast / triage-later loop
Vault Security Policy	Secret management and Git safety rules
QuickAdd Inbox Optimization Guide	Capture templates and inbox processing
Weekly AI Summary Guide	Weekly review generation and its data requirements

---

🛠️ Installation & Setup Guide

Step 1: Clone or Open Vault in Obsidian

1. Download or clone this repository to your local computer:

   git clone https://github.com/lowqualityloey/loey_space.git
   

2. Open Obsidian, click Open folder as vault, and select the loey_space directory.

Step 2: Environment Credentials Setup (.env)

Copy the example file and fill in your API keys:

cp .env.example .env

Then edit .env with your real credentials:

# Required for AI enrichment (daily summaries, concept analysis, dev note analysis)
GEMINI_API_KEY=your_google_gemini_api_key_here

# Optional - Weather Dashboard project
VITE_OPENWEATHER_API_KEY=your_openweather_api_key_here

# Optional - OpenAI fallback
OPENAI_API_KEY=sk-your_openai_api_key_here

[!IMPORTANT] Getting a Gemini API Key (required for AI features):

1. Go to Google AI Studio
2. Click Create API Key
3. Copy the key and paste it into your .env file

The .env file is listed in .gitignore and will never be pushed to version control.

[!WARNING] If .env is missing or GEMINI_API_KEY is not set:

• AI Daily Summary (Ctrl+Shift+A) will show an error notice
• Weekly AI Summary generation will fail
• Concept and Dev note enrichment will not work
• All other vault features (tasks, habits, navigation, dataview queries) work normally without an API key

Step 3: Enable Core Community Plugins

Go to Obsidian Settings -> Community Plugins and ensure the following plugins are enabled:

• HomePulse — Dashboard command center & 2-way habit synchronization.
• QuickAdd — Automation macros & 1-click note generation blueprints.
• Templater — Dynamic date calculation & variable expansion.
• Dataview — Real-time indexer queries for MOCs & task tracking.
• Kanban — Visual board view for project workflows.
• Kanban Status Sync — Keeps card checkboxes in step with their lane (bundled in this vault, not from the store).
• Calendar — Visual daily note navigator.
• Activity History — Contribution heatmap for the dashboard.

[!IMPORTANT] Pre-Configured HomePulse Plugin: This vault comes pre-configured with an enhanced build of the HomePulse plugin located in .obsidian/plugins/homepulse/ (featuring 2-way real-time habit file sync, dynamic Tech Tree scanner, deferred dashboard refresh, and QuickAdd daily note macro integration). Do not re-install or auto-update HomePulse from the Obsidian Community Store, as doing so will overwrite these custom integrations with standard plugin code. Disable automatic plugin updates in Obsidian (Settings -> Community plugins -> Auto-update plugins: OFF).

Step 4: Launch HomePulse Dashboard

• Click the HomePulse icon on the ribbon action bar or press Ctrl + P and execute HomePulse: Open Dashboard View.

---

💡 Daily Workflows & Keyboard Shortcuts

1-Click Note Creation Shortcuts

Use QuickAdd ribbon buttons or command palette (Ctrl + P -> QuickAdd: Run...):

• ⏳ Create Daily Note — Generates today's daily log (01-Daily/YYYY-MM-DD.md) with habits, energy tracking, and task lists.
• 💡 Create Concept Note — Creates a structured evergreen note in 08-Concepts/.
• 💻 Create Dev Note — Creates a technical code pattern in 03-Dev/.
• 📥 Quick Capture to Inbox — Appends a quick note to the inbox dump (timestamped).
• 🧹 Archive & Clear Quick Capture Dump — Archives processed entries to 00-Inbox/Archives/ and resets the dump note.
• 🚀 Create Project Note — Scaffolds a new project with folder and kanban.
• 🔄 Sync GitHub Project Kanban — Bi-directionally syncs the active project board with GitHub Projects v2 (via left ribbon button lucide-github or QuickAdd).

Multi-Domain AI Enricher (Ctrl + Shift + A)

Position your cursor inside any active note and press Ctrl + Shift + A (or run QuickAdd: AI Enrich Note):

1. Daily Notes (01-Daily/): Generates a narrative summary, AI reflection, inspirational quote, and suggested next step.
2. Concept Notes (08-Concepts/): Detects topic domain and generates technical explanations, examples, and related concept links.
3. Dev Notes (03-Dev/): Analyzes code snippets and updates tags, context, explanation, and wikilink references.

Inbox Triage (token sweep)

Triage is a decision, not a form. Append a token to any line in 00-Inbox/quick-capture-dump.md:

- i have to do laundry #do
- https://app.lofi.town/ #ref
- semantic commit messages #concept
- lemme test #bin

Then run QuickAdd: 🧹 Triage Sweep once. #do becomes a task in today's daily note; #dev / #concept / #learn / #ref / #personal become real notes with the right frontmatter; #project scaffolds a project folder plus Kanban board; #bin is dropped. Untagged lines stay put, and swept lines are logged (struck through, with their destination) in a ## ✅ Triaged section rather than deleted.

At session start, Kiro reports the current state — e.g. "Inbox: 9 items, oldest 7 days. None tagged yet." — instead of nagging on every message.

Weekly AI Summary

Run QuickAdd: 📊 Weekly AI Summary (or bind to Ctrl+Shift+W):

• Aggregates 7 days of daily notes (mood, energy, tasks, habits, wins, blockers)
• Generates executive summary, patterns, and recommendations via Gemini AI
• Creates a structured review note in 07-Reviews/YYYY-W[week].md

---

📱 Mobile Workflow

Designed for capture fast, triage later. All mobile commands land in inbox with 📱 marker.

Mobile Commands (add to Obsidian Mobile toolbar)

Command	What it does
📱 Mobile Capture	Appends thought to inbox with timestamp
📱 Mobile Task	Appends as checkbox to inbox
📱 Mobile Idea	Creates structured idea note in inbox
📱 Mobile Add to Daily	Adds task directly to today's daily note

Setup

1. Install Obsidian Mobile and sync the vault
2. Go to Settings -> Mobile -> Manage toolbar
3. Add the 📱 QuickAdd commands
4. Capture in < 10 seconds, batch-process on desktop

See 06-Resources/Mobile Workflow Guide.md for full setup instructions.

---

📊 Habit Analytics

The Habit Analytics Dashboard (01-Daily/Habit Analytics Dashboard.md) provides:

• Overall Completion Rate — 30-day rolling percentage with per-habit progress bars
• Daily Heatmap — Last 14 days showing which habits were completed each day
• Day-of-Week Patterns — Which days you're most/least consistent
• Streak Analysis — Current and longest streaks for each habit
• Trend Analysis — 7-day moving average with trend indicators
• Improvement Recommendations — Identifies habits below 70% and suggests fixes

All data is automatically pulled from daily notes — no manual tracking required.

---

📋 Task System Rules & Conventions

• Source of Truth: All tasks are logged directly inside daily notes (01-Daily) or project notes (02-Projects).
• Task Status Hierarchy:
  • - [ ] task => Active To-Do (Visible in Open Tasks widget & _Tasks MOC.md)
  • - [/] task => In Progress (Sorted to top, focus anchor)
  • - [x] task => Completed (Logged in task analytics)
• Habit Isolation: Routine checkboxes under ## 🔁 Habits are strictly isolated from task command centers.
• Kanban Filtering: Tasks under ## Backlog and ## Archive in project kanbans are excluded from the Open Tasks widget and _Tasks MOC.md.
• Lane-Driven Status: Card markers are set automatically from the lane a card sits in (To Do -> [ ], In Progress / Review / Test -> [/], Done -> [x] + ✅ date). Cancelled/forwarded markers ([-], [>], [<]) are preserved.
• Tick Anywhere to Complete: Ticking a project card from the board, _Tasks MOC.md, or the daily note's project query moves that card to the Done lane with today's date.
• Project Tasks in Daily Notes: Daily notes show in-progress project work through a live Dataview query (#### 🎯 In Progress from Projects), not copied text — so nothing is double-counted in the Open Tasks widget and nothing leaks into the next day's carry-over. A CSS snippet (project-tasks.css) draws these [/] cards as empty checkboxes inside daily notes, so they read as ordinary open tasks you can tick; cards completed that day stay listed, checked.
• Project Status Matching: _Projects MOC.md accepts in progress, in-progress, active, doing and wip as active, so a space instead of a hyphen no longer hides a project. Progress bars count committed work only — Backlog and Archive are excluded.
• Daily Carry-Over: Unfinished - [ ] tasks under ### ✅ Tasks roll forward into tomorrow's daily note. Completed and in-progress items do not.
• Forwarded, Not Duplicated: When tasks carry forward, the previous note marks its copies - [>] (forwarded, shown as a faint →). Each task is therefore open in exactly one note, so it is counted once in the Open Tasks widget, _Tasks MOC.md, and the analytics.
• GitHub Project v2 Sync: Project Kanbans with github_project_number frontmatter sync cards, status columns, and priority tags (#priority/p0 Red 🔴, #priority/p1 Yellow 🟡, #priority/p2 Blue 🔵, #priority/p3 Green 🟢) bi-directionally with GitHub Projects v2.
• Today-Scoped Dashboards: _Tasks MOC.md counts daily tasks from the current daily note only; project board tasks are always included. Completed totals stay all-time.

---

🎨 Styling & Aesthetics

• Ultra-Dark Palette: Designed around a high-contrast #0C0D13 background, sleek card containers, and glassmorphic borders (.obsidian/snippets/dashboard-cards.css).
• Mobile HomePulse: homepulse-mobile.css overrides the dashboard's fixed 5-column grid and 132px row height on phones, so cards go full width and grow to fit. Execution Pulse and Knowledge Profile drop to 2×2, the calendar's weekday labels centre over their columns, and tap targets are raised to 32px.
• Typography System: Custom Google Fonts hierarchy (.obsidian/snippets/fonts.css):
  • Body / UI: Inter, Plus Jakarta Sans, Outfit
  • Code / Monospace: JetBrains Mono

---

🔒 Security & Git Safety

• No Hardcoded API Keys: All machine credentials and API tokens strictly reside in .env (git-ignored).
• Private Notes Directory: The .secrets/ directory is strictly excluded from Git tracking for storing sensitive personal documents.
• Session Validation: Kiro IDE hooks check .env presence on startup and warn if API keys are missing.
• Vault Security Policy: Read the official Vault Security Policy for complete guidelines.

🪝 Enabling the pre-commit guard

A commit-blocking hook ships in .githooks/pre-commit, but Git does not use it until you point at it. Run this once per clone:

git config core.hooksPath .githooks

On a fresh clone, also mark it executable so it survives on other machines:

git update-index --chmod=+x .githooks/pre-commit

It refuses a commit when the staged changes include:

Check	Blocks
Paths	.env, .env.*, .secrets/, 00-Private/, *_secret*, *_private*
Content	Google/Gemini (AIza…), OpenAI (sk-…), GitHub tokens, AWS key IDs, PEM private keys, and *_API_KEY= with a real-looking value
Advisory	Warns if sensitive files are already tracked from earlier commits

Placeholders such as your_google_gemini_api_key_here are allowed, so .env.example and the docs quoting it still commit cleanly. Only added lines are scanned, and any match is redacted in the output rather than echoed back. Deliberate override: git commit --no-verify.

[!WARNING] The hook is a local guard, not a net. It cannot help a machine that hasn't run the core.hooksPath command, and it runs before the push — so also switch on GitHub secret scanning + push protection (repo Settings → Code security). That blocks server-side, and unlike a CI workflow it acts before the commit becomes public.

If a key ever does reach a public commit, rotate it. Rewriting history does not un-leak it.

---

🧯 Troubleshooting

Symptom	Cause and fix
⚠️ GEMINI_API_KEY missing in .env!	No key configured. Run cp .env.example .env and paste a key from Google AI Studio.
AI summary reads flat, with a notice about quota	Gemini refused with HTTP 429 and the offline fallback wrote the text. The notice names which limit: a per-minute limit clears in about a minute; a daily limit does not, and resets at midnight Pacific. Re-run Ctrl + Shift + A afterwards to replace it.
A bundled plugin or CSS change has no effect	Obsidian loads plugins, snippets and hooks at startup. Run Ctrl + P → Reload app without saving.
🧹 Triage Sweep missing from the palette	Register it once: Settings → QuickAdd → Manage Macros → new macro → Add User Script → triage-sweep.js, then add it as a Macro choice.
Sweep says "no daily note for <date>"	#do files into today's note, which must already exist. Run QuickAdd: Create Daily Note first.
HomePulse lost its custom behaviour	It was updated from the Community Store. Restore .obsidian/plugins/homepulse/ from Git history and set Auto-update plugins: OFF.
Habit toggles don't reach the daily note	Sync needs today's note at 01-Daily/YYYY-MM-DD.md with a ## 🔁 Habits section, and Dataview enabled.
Dashboard cramped or overlapping on mobile	Enable the homepulse-mobile snippet: Settings → Appearance → CSS snippets.

🔧 Maintenance

• Updating plugins — safe for store plugins (Dataview, Templater, QuickAdd, Kanban, Calendar, Activity History). Never for homepulse or kanban-status-sync, which are local builds with no store equivalent.
• Restyling the dashboard — HomePulse's own styles.css is regenerated on rebuild, so put overrides in .obsidian/snippets/ instead. That's what homepulse-mobile.css and dashboard-cards.css do.
• After editing .kiro/hooks/ — reload the app; hooks are read once at session start.

---

🤝 Contributing

The system is open to contributions; the journal isn't. PRs are welcome for the Kanban Status Sync plugin, the automation scripts, CSS snippets, the pre-commit hook, templates and docs. The numbered content folders are personal notes and are closed to PRs — though issues are welcome about anything.

See CONTRIBUTING.md for the full scope, plus how to test any script under plain Node by mocking app.vault — no Obsidian install and no risk to real notes.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for complete details.