Document the `managed:` repository field and `--no-managed` workspace sync flag

[christso]

Summary

The managed: field on repositories[] in workspace.yaml, and the matching --no-managed flag on allagents workspace sync, are real features in the code (v1.7.2) but are not documented in any user-facing surface I could find. This issue asks for them to be added to the docs.

What the feature does

From dist/index.js (v1.7.2):

// shouldClone / shouldPull gatekeepers
function shouldClone(managed) {
  if (managed === undefined || managed === false) return false;
  return true;
}
function shouldPull(managed) {
  if (managed === true || managed === "sync") return true;
  return false;
}

// processManagedRepos — called during `allagents workspace sync`
async function processManagedRepos(repositories, workspacePath, options2 = {}) {
  if (options2.skipManaged || options2.offline || options2.dryRun) return [];
  const managed = repositories.filter((r) => r.managed);
  if (managed.length === 0) return [];
  for (const repo of managed) {
    // ...
    if (!existsSync(absolutePath)) {
      if (!shouldClone(repo.managed)) { /* skip */ continue; }
      await cloneRepo(url, absolutePath, repo.branch);
    } else if (shouldPull(repo.managed)) {
      await pullRepo(absolutePath, repo.branch);
    }
  }
}

So in practice:

• A repositories[] entry with managed: true causes allagents workspace sync to git clone the repo from source / repo into path if the path doesn't exist, and git pull it if it does exist and is clean.
• managed: "sync" behaves like true for both clone and pull.
• A truthy-but-not-true value (anything that passes the generic filter) causes a clone on first run but no subsequent pull.
• Omitting managed: (or setting it to false) causes allagents workspace sync to leave the repo entirely alone.
• Passing --no-managed to workspace sync sets skipManaged: true and short-circuits the whole function, regardless of what any repo has in its managed: field.

Where it's currently surfaced

Surface	Status
allagents workspace sync --help	✅ Flag shown: --no-managed - Skip managed repository clone/pull operations [optional]
dist/index.js source	✅ First-class flag, flag({ long: "no-managed", ... })
https://allagents.dev (public docs site)	❌ Not found on any page I could reach
docs/src/content/docs/docs/reference/cli.mdx in the repo	❌ No mention of --no-managed
docs/src/content/docs/docs/reference/configuration.mdx	❌ No mention of managed: on repositories[]
docs/src/content/docs/docs/guides/workspaces.mdx	❌ The example repositories: block omits managed: entirely

Why this matters

The behavior is security- and correctness-relevant for anyone using allagents in a pipeline where another tool is already materializing repositories:

• In a CI job that pre-downloads a pinned snapshot into a workspace directory, then calls allagents workspace sync to install skills/plugins/MCP servers, any stray managed: true entry silently causes allagents to overwrite the pre-materialized repo with git clone or mutate it with git pull. That's a real footgun — a copy-pasted YAML from another project could silently drift a pipeline's pinned source code to upstream HEAD.
• Downstream users reading the docs have no way to discover either the feature (when they want it) or the escape hatch (when they explicitly don't). Today the only way to learn about it is reading the CLI --help output or the source.
• Undocumented CLI flags are a semver hazard. If a future release renames --no-managed or folds it into a different flag, any downstream pipeline relying on the current name breaks with an "unknown flag" error. Documenting it means it becomes part of the published contract.

Suggested doc additions

1. docs/src/content/docs/docs/reference/configuration.mdx — add managed: to the repositories[] schema

Something like:

repositories:
  - path: ../my-project
    source: github
    repo: myorg/my-project
    managed: true        # optional — see below

managed (optional, default: omitted)

Controls whether allagents workspace sync clones or pulls this repository.

• Omitted or false — allagents never touches the repository. Use this when another tool is responsible for materializing the source tree (e.g. a CI script that downloads a pinned snapshot).
• true — allagents will git clone the repository from source/repo into path if it does not exist, and git pull it on subsequent syncs if the working tree is clean and on the expected branch.
• "sync" — equivalent to true.

The source and repo fields are required when managed is truthy.

2. docs/src/content/docs/docs/reference/cli.mdx — document --no-managed under workspace sync

allagents workspace sync [--no-managed]

  --no-managed   Skip git clone/pull operations for all repositories,
                 regardless of their managed: field. Use this when
                 another tool is responsible for populating repository
                 directories and allagents should only handle plugins,
                 skills, and AGENTS.md sync.

3. docs/src/content/docs/docs/guides/workspaces.mdx — add a short section on the managed vs unmanaged model

A paragraph explaining the "who owns the repo directory" split would help downstream users reason about it:

By default, allagents treats repositories[] entries as references only — it uses them for AGENTS.md / CLAUDE.md propagation and skill discovery, but it does not clone or pull the underlying git repository. To have allagents manage the repository directory itself, set managed: true on the entry. To explicitly disable repository management for a single sync run (for example, when a CI job has already populated the directory), pass --no-managed to allagents workspace sync.

Happy to contribute

I can put up a docs PR with the three changes above if that would help — just confirm the desired wording and I'll follow the existing docs voice.

Context

I hit this while wiring up a pinned per-year snapshot artifact pipeline in WiseTechGlobal/WTG.AI.Prompts (PR #536). Our CI materializes each eval workspace at an optional pinned commit before calling allagents workspace sync to install skills, and I went looking for a documented way to make sure allagents could never clobber the pre-materialized tree. I found --no-managed in the CLI --help output but couldn't find any mention of it (or the corresponding managed: field) in the allagents.dev docs or the reference docs in this repo.