vault

Files (5)

• SKILL.md
• add-frontmatter.sh
• add-stars.sh
• github-stars-map.yaml
• rebuild-feeds.sh

SKILL.md (first lines)

# Vault

The vault is a PARA-structured Obsidian brain. Other skills read and write it.

## Location

```bash
VAULT=./work/vault   # from the harness root
```

## If there is no vault

Don't ask at session start. The first time a task needs the vault:

1. Ask once: "Do you have an Obsidian vault? Where is it?"
2. If they have one elsewhere, link it: `ln -s "<their vault>" work/vault`.
3. If not, create it:

```bash
mkdir -p "work/vault/"{"01 Projects","02 Areas","03 Resources","04 Archive",Clippings}
```

Then carry on with the original task.

## Structure

- `01 Projects/` -- active work with an end
- `02 Areas/` -- ongoing interests
- `03 Resources/` -- reference material
- `04 Archive/` -- inactive items
- `05 journal/` -- yearly journals
- `Clippings/` -- saved articles and links inbox (categorize into PARA sections)
- `Unsorted/` -- secondary inbox for uncategorized links

Each subfolder has a `:feed.md` with a dataview query listing its contents by date added. `:feed.md` is the convention for "show me what's in this section."

## Reading the vault

Use `read`, `rg`, or `find` directly against `$VAULT`. Examples:

```bash
# list a section
ls "$VAULT/02 Areas/Music/"

# literal search across the vault
rg -l "cowpunk" "$VAULT"

# show a section's feed
cat "$VAULT/02 Areas/Music/:feed.md"
```

For semantic search ("what notes feel related to X"), no tool exists yet -
fall back to `rg` with synonyms.

## Recent activity

When asked "what's been happening recently in my vault" or "what's new":

```bash
# 1. Current journal -- newest entries at the bottom
read "$VAULT/05 journal/Journal.md"
read "$VAULT/05 journal/Journal $(date +%Y).md"

# 2. Most recently modified files across the vault (excludes dot dirs)
find "$VAULT" -name "*.md" \
  -not -path "*/.obsidian/*" -not -path "*/.git/*" \
  -exec stat -f "%m %Sm %N" {} + 2>/dev/null \
  | sort -rn | head -30

# 3. Recently added files per section (by ctime = when file was created)
for section in "01 Projects" "02 Areas" "03 Resources"; do
  find "$VAULT/$section" -name "*.md" -not -name ":feed.md" \
    -exec stat -f "%m %Sm %N" {} + 2>/dev/null \
    | sort -rn | head -10
  echo "---"
done

# 4. Check inboxes
find "$VAULT/Clippings" -name "*.md" -mtime -30 2>/dev/null | sort
find "$VAULT/Unsorted" -name "*.md" -mtime -30 2>/dev/null | sort
```

**Note**: All files in the vault may share the same ctime/mtime (common after a git clone or bulk operation). In that case, rely on the journal content and `created` date in YAML frontmatter instead of filesystem timestamps.

Also check specific project notes for structured updates (release notes, TODOs, design briefs):

```bash
for project in "$VAULT/01 Projects"/*/; do
  echo "=== $(basename "$project") ==="
  ls "$project" | grep -i -E "(todo|release|log|status|notes|update)" | head -5
done
```

## How feeds work

Each `:feed.md` contains a Dataview query that reads `created` (YAML frontmatter) to list items chronologically. Starred repos appear alongside regular notes by their repo creation date. The `github` column shows `owner/repo` for stars, blank for regular notes:

```dataview
TABLE created AS "Date", github AS "Source"
FROM "02 Areas/Music"
WHERE file.name != ":feed"
SORT created DESC
```

Regenerate all feeds from `skills/vault/`:

```bash
bash rebuild-feeds.sh
```

## Maintenance

```bash
./add-frontmatter.sh       # batch add YAML frontmatter to files missing it (extracts source URL, author from domain)
./add-stars.sh             # sync GitHub starred repos into vault (idempotent, skips existing via github: frontmatter key)
./rebuild-feeds.sh         # regenerate all :feed.md files (runs after add-stars.sh to surface new entries)
```

### GitHub stars sync

From scott-fryxell/brayness, MIT.

More from scott-fryxell/brayness