Skip to content

CODE: garden tools

feralcoder edited this page Nov 11, 2026 · 33 revisions

Up Links

Public

feralcoder public Home

Private

(private) Top Level Wiki
(private) Feralcoder IT

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.

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

fcdocs / First_Docs

fcdocs Is the collection of scattered feralcoder documentation sources. A old private/public (workstation/shared) wikis, github.io wiki, oneNote, thoughtVault (and no obsidian?)

fcdocs / publish

This garden may be a curated subset of some elements of fcdocs. For publication, obviously.

fcenv / cliff-dev

fcenv Is the collection of tools and configuratons used to build specific feralcoder environments.

cornucopulator / AI_Tools

cornucopulator is my whole set of AI tools and knowledge.

cornucopulator / demonstration-alphabet

This garden might be a curated and staged set of my AI tools for a client or employer.

Clone this wiki locally