Managed Artifacts

FlyDocs delivers skills, hooks, commands, cursor rules, and rendered config files from the server. These are managed artifacts -- the server owns them, and they are kept in sync automatically. You do not install or update them manually; the CLI handles it.

What are managed artifacts

Managed artifacts are files installed into your project by FlyDocs that are owned by the server. When the server publishes updates, running flydocs sync or flydocs update pulls the new versions into your project. You never need to download, copy, or configure these files yourself.

Every artifact belongs to one of these categories:

How sync works

Artifacts have a monotonic version number across the entire catalog. The CLI caches the last-seen version locally. When you run sync, it requests only artifacts newer than that version:

# Pull latest artifacts from the server
flydocs sync

Behind the scenes, the CLI calls GET /api/relay/artifacts?since=N where N is the last version it received. The server returns only artifacts with a version greater than N. This keeps sync fast -- you only download what changed since your last update.

After receiving new artifacts, the CLI writes them to disk, updates the local version counter, and regenerates integrity hashes. Your hooks, skills, and commands are immediately available in your next AI session.

Workspace-specific rendering

Some artifacts are not static files -- they are rendered on-demand based on your workspace configuration. When the CLI sends the X-Workspace header, the server renders CLAUDE.md and AGENTS.md with workspace-specific content:

• Installed skills table with entry points and triggers
• Command triggers mapped to skill procedures
• Section references for the workspace's active skill set

These rendered artifacts bypass the version filter. They always return the latest rendered version because their content depends on your workspace state, not a global artifact version.

Managed vs user-maintained

Not everything in your project is managed. FlyDocs draws a clear line between files the server owns and files you maintain. Understanding this boundary tells you what flydocs update will and will not touch.

The rule is simple: if it lives under .claude/, .cursor/, or .flydocs/templates/, the server owns it. If it lives under flydocs/, you own it. See File Structure for the complete directory map.

Protecting local changes: skipPaths

If you are actively developing a managed path -- for example, modifying a skill for testing or experimenting with a hook -- you can prevent sync from overwriting your changes. Add the path to artifactOverrides.skipPaths in .flydocs/config.json:

{
  "artifactOverrides": {
    "skipPaths": [".claude/skills/flydocs-workflow/"]
  }
}

Paths listed here are excluded from artifact sync. This is CLI-local only -- not stored on the server, not visible in the portal, and preserved across syncs. When you are done with local changes and want to receive server updates again, remove the entry.

Integrity checking

Managed artifacts have SHA-256 hashes tracked in .flydocs/integrity.json. The integrity system detects drift -- local modifications to managed files that could cause unexpected behavior.

• Hashes are checked with a 30-minute TTL cache to avoid redundant computation
• Drift detection runs on session start via the session-start.py hook
• If drift is detected, flydocs update will overwrite the local file with the server version
• Files listed in skipPaths are excluded from drift detection
• Running flydocs update resets all integrity baselines

If you intentionally modified a managed file and want to keep those changes, add the path to skipPaths before running update. Otherwise, the server version takes precedence.

Triggering an update

There are several ways to pull the latest managed artifacts:

For most workflows, artifacts stay current automatically. flydocs init pulls the latest version on setup, and /start-session checks for updates at the beginning of each session. Explicit sync is only needed if you want to force an immediate update.