Skip to content

CODE: garden tools

feralcoder edited this page Nov 14, 2026 · 33 revisions

Up Links

Public

feralcoder public Home

Private

(private) Top Level Wiki
(private) Feralcoder IT

cornucopulator
fcdocs
fcenv
MusicMind

Catalog / Garden Structure

A catalog is a named logical collection of repos (submodules) at published versions, implemented itself in a repo. It is a lightweight umbrella: a list of names, URLs, and SHAs. Its weight is entirely referential — it points at things; it does not contain them.

A garden is a physical catalog checkout — a live working instance on a specific machine. It is frequently on a branch of the same name (eg the AI_Tools garden lives in branch "AI_Tools"). Its submodules may be on their own branches of same or different name.

A garden is reconstructible: delete it and rebuild it from the catalog in minutes. Its definition (branch, policy, IDE wiring) lives on the garden branch.

One catalog → many gardens (different machines, different branch policies).

One of the submodules in all gardens is garden-tools, which provides the bootstrap scripts, policy hooks, and lifecycle tooling described below.

CODE

CODE: https://github.com/feralcoder/garden-tools

WIKI: https://github.com/feralcoder/garden-tools/wiki

Bootstrapping An Existing Garden

git config --global garden.codeRoot    ~/Workspace/repos/workspace
git config --global garden.gardenRoot  ~/Workspace/repos/GARDENS
git config --global garden.catalogRoot ~/Workspace/repos/CATALOGS
# POR EXEMPLO:
CATALOG=cornucopulator
GARDEN=AI_Tools
GARDEN_HOME=~/Workspace/repos/GARDENS              # Here's where we'll work in the AI_Tools garden
CATALOG_HOME=~/Workspace/repos/GARDENS/_CATALOGS   # Catalog/Garden Metadata DON'T MESS HERE
CODE_HOME=~/Workspace/repos/workspace              # Standalone Code Checkouts Here
mkdir -p $CODE_HOME $CATALOG_HOME $GARDEN_HOME/$CATALOG && cd $CATALOG_HOME

To check out the existing shared garden on a particular location:

# 1. Clone the catalog repo
git clone git@github.com:feralcoder/$CATALOG.git catalog-$CATALOG
cd catalog-$CATALOG

# 2. Initialize submodules defined by the catalog (incl. garden-tools)
git submodule update --init

# 3. Stand up the AI_Tools garden — creates the garden worktrees and
#    clones the child repos defined in .garden-catalog
./garden-tools/scripts/garden-init.sh $GARDEN $GARDEN_HOME/$CATALOG/$GARDEN garden/$GARDEN

That produces:

  • $GARDEN_HOME/$CATALOG/$GARDEN — garden worktree on garden/$GARDEN with all submodules checked out on their target branches
  • $GARDEN_HOME/$CATALOG/$GARDEN-main (or {name}-main) — the read-only base mirror worktree
cd $GARDEN_HOME/$CATALOG/AI_Tools
./garden-tools/scripts/garden-refresh-base.sh --include-utility --execute   # pull bases, merge up
./garden-tools/scripts/garden-push-state.sh --include-utility --execute     # push state (dry-run without --execute)

How It Works

Worktree-Shared-Store Layout

Each catalog has one canonical clone (object store) plus garden directories as linked git worktrees on that shared store. Child repos worktree the same way on their own object stores:

workspace/feralcoder/catalog-{name}/   ← canonical catalog clone (main)
GARDENS/{name}/{Garden}/               ← catalog worktree (garden branch)
GARDENS/{name}/{Garden}/{child}/       ← child repo worktree (garden branch)

Branch Roles

  • catalog main — distributable snapshot, submodule-pinned. Immutable history.
  • catalog garden/<Name> — garden definition: .gitignore, .worktree-policy, .devin/ (IDE face), installers.
  • child main — upstream/distribution base, fast-forward only.
  • child utility — shared writable integration branch pinned by garden snapshots.

Inclusion Kinds

  • Conceptual submodule — part of the garden's working concept. Worktrees in on the garden branch, participates in garden branch policy, pinned at a garden-specific SHA.
  • Utility inclusion — glue that makes the machinery work (eg garden-tools, thoughtVaultClients). Does not participate in concept policy.

Policy and Hooks

  • .worktree-policy at each worktree root declares desired branch, enforcement level (advisory / warn / block), and whether branch switching is allowed.
  • Catalog hooks install once on the canonical catalog clone and are shared by all catalog worktrees (establish-catalog-hooks.sh).
  • Repo hooks install once per child/utility object store (install-worktree-hooks.sh).
  • Hooks fire on post-checkout, post-merge, pre-commit: desired-branch checks, singleton locks, submodule alignment, branch-switch blocks.

Garden Types

  • Advisory — normal working surface. Warns on policy violation, never blocks.
  • Singleton — locked working surface, branch switching blocked. Used for sync bridges (Obsidian sync), read-only mirrors, controlled ingest points.

Snapshot / Publish Lifecycle

  • garden-checkout.sh — position branches across the garden (positioning ≠ synchronization).
  • garden-refresh-base.sh / garden-sync-up.sh — pull origin/main, merge main upward.
  • garden-snapshot.sh — commit current submodule refs (gitlinks) to the garden branch.
  • catalog-snapshot.sh — publish garden state back to catalog/submodule base branches.
  • garden-push-state.sh — push target/base/mirror branches without force.

Reconstruction on a New Machine

git clone <catalog-remote> workspace/feralcoder/catalog-<name>
cd workspace/feralcoder/catalog-<name>
git submodule update --init           # gets garden-tools
./garden-tools/scripts/establish-catalog-hooks.sh
./garden-tools/scripts/garden-init.sh <garden-name> <path> <branch>

Examples

cornucopulator is my whole set of AI tools and knowledge.

Type: advisory — desired_branch = garden/AI_Tools, warns never blocks.
Conceptual (on garden/AI_Tools): thoughtVault, thoughtVaultMCP, thoughtVaultClients, thoughtVaultDockets, dworkinsPattern, machine-ops.
Utility: garden-tools (base main, target utility).

Note thoughtVaultClients is conceptual here but utility in other gardens — role is per-garden, not per-repo.

fcdocs is the collection of scattered feralcoder documentation sources — realized on disk as the three old wikis plus thoughtVault.

Type: advisory — desired_branch = garden/First_Docs.
Conceptual: workstation.wiki (old private wiki), shared.wiki (old public wiki), feralcoder.github.io.wiki (github.io wiki), thoughtVault.
Utility: garden-tools.

oneNote is not (yet) a submodule — it lives outside as GARDENS/oneNote_Obsidian_Exports, an unmanaged staging dir.

fcenv is the collection of tools and configurations used to build specific feralcoder environments.

Type: advisory — desired_branch = garden/cliff-dev.
Conceptual: machine-ops (ansible), workstation, bootstrap-scripts, myenv, machine-bootstrap.
Utility: garden-tools, plus thoughtVaultClients pinned on main.

frutenlumens / Obsidian_Sync

The Obsidian↔git sync bridge — the production example of a singleton garden.

Type: singleton — enforcement = block, allow_branch_switch = false, lockfile /tmp/frutenlumens-obsidian.lock. Changes aggregate one-way on garden/Obsidian_Sync, then promote to main on schedule.
Conceptual: thoughtVault, thoughtVaultDockets, thoughtJournal.
Utility: garden-tools, thoughtVaultClients (both on main).

fcdocs / publish (proposed)

Not on disk yet. A curated subset of First_Docs, for publication. Likely advisory, with the wiki repos as conceptual inclusions and a stricter publish flow via catalog-snapshot.sh.

cornucopulator / demonstration-alphabet (proposed)

Not on disk yet. A curated and staged set of my AI tools for a client or employer — same catalog as AI_Tools, different garden branch and submodule subset.

Clone this wiki locally