project

func Discover ¶

func Discover(start string) (root string, found bool, err error)

Discover walks up from start looking for a project source tree: a DirName directory. Returns the project root (the directory CONTAINING DirName) and found=true on the nearest match. Returns ("", false, nil) when no project tree exists at or above start.

If it encounters the retired single-file LegacyMarkerFile at a directory that has no DirName tree, it returns a migration error rather than silently ignoring it — a project that worked under M5 must not quietly lose its config. A DirName tree always wins over a legacy file at the same directory.

func Home ¶

func Home(root string) string

Home returns the project canonical home (<root>/.agentsync) for a project root.

func Merge ¶

func Merge(base, proj source.Canonical) source.Canonical

Merge overlays the project-scope canonical `proj` onto the user-scope `base`, returning a new Canonical. It never mutates base.

Semantics (documented in docs/architecture.md §project overlay):

• Agents: the project's agent map is AUTHORITATIVE — project scope renders only to agents the project itself declares, so the committed tree produces the same render on every collaborator's machine. Base (user-scope) agents are never inherited; an empty project agent map merges to an empty agent set (scope-aware commands reject it before rendering — see requireProjectAgents in internal/cli).
• MCP / LSP / Skills / Subagents / Commands: overlaid by identity (ID or Name) — a project entry replaces a base entry with the same key, and a new key is appended. Order is base-first, then appended project entries.
• Hooks: overlaid by Event — if the project declares any hook for an event, its hooks for that event REPLACE all base hooks for that event (hooks are a per-event set, not individually addressable).
• Memory: base body then project body, concatenated (project appended).
• Plugins / Marketplaces: project entries are not modeled at project scope in v1 and are inherited from base unchanged (see the migration note in docs/architecture.md). Config (Updates/Secrets/Memory) is inherited from base unless the project declares its own non-zero values; the effective [memory] setting is also propagated onto the stored project overlay so project-scope render honours a user-level managed-banner opt-out. The [destination_directory_git_backup] table is deliberately NOT overlaid: git backup is a user-scope-only feature (VersionRoots returns nil at project scope and runDestinationGitBackup is gated to user scope), so a project override could never take effect — copying it would be silently inert (issue #126).