Use cases

Mossbear holds many kinds of artifact: rules, skills, and other project docs. Each one has a single editable source of truth at a time: Mossbear by default, git after an explicit promotion. Working that out for nine different situations turned up the same shape three times, so that’s how this page is organized.

Which shape fits

Two questions place you: who edits this day to day, and whether a change needs review before it takes effect. Neither applies to a private note, so Mossbear is the source of truth and there’s nothing to commit. Both apply to repository policy, so git is the source of truth instead, and Mossbear’s job is to record and distribute the reviewed revision, never to become a second place the file can be edited.

Shape	Who edits it	What moves it
Mossbear is the source of truth	You, through the dashboard or an agent	mossbear refresh delivers it
Git is the source of truth	Whoever can commit to the repo	A commit, then mossbear publish
Moving between the two	You, deliberately	mossbear promote, then a commit

Mossbear is the source of truth

This is the default, and most of it needs no command from you at all: an agent capturing a note with create_artifact, or you saving one from the dashboard, is already done. mossbear refresh keeps it current wherever you use it.

Private notes and handoffs. Capture these from the dashboard’s inbox, or let an agent push one on your behalf. Either way, they never touch git.

A skill or note you want in every repo, not just this one. Whether it started as a file you mossbear linked or something you wrote straight into Mossbear, pull the bundle it’s in with --deliver global:

mossbear pull <bundle> --deliver global

That lands it in your machine-wide skills. Every repo you work in gets it without a copy living in any of them. This needs one thing first. Run mossbear init on this machine and agree when it asks about writing to your global skills. Skip that and the pull still reports success, but nothing lands there; mossbear status is what tells you the write never happened.

A live plan or brief a few people share. Put the bundle in a shared workspace (see Workspaces and sharing) and have each repo that needs it subscribe:

mossbear pull <bundle>

Anyone with access can edit it, in the dashboard or on disk, and it shows up on the next refresh. There’s no commit and no review gate. That’s the trade for it being fast to change.

Git is the source of truth

Anything that needs a second author and a review gate stays a normal git file. Mossbear’s job is to grade it, record the revision that shipped, and deliver it to whoever subscribes.

A guide already in your repo. Bring AGENTS.md, CLAUDE.md, or a .claude/skills/ directory into Mossbear once:

mossbear link

Nothing about how you edit the file changes afterward. Mossbear keeps reading it from disk.

A skill pack your team distributes. Create the bundle from the dashboard, then claim it as this repo’s home:

mossbear pull team-skills --home

The first publish needs a path, since nothing is declared yet; it adds the path to published.paths so every later publish keeps covering it:

mossbear publish skills/review.md

From then on, a bare mossbear publish after a commit that touches a declared path republishes it, and each repo that should receive the pack subscribes the normal way:

mossbear pull team-skills

publish reads only what git committed. An edit you haven’t committed yet is named and left alone, never sent. Delete a published file and commit the deletion, and the next publish withdraws it from subscribers. The artifact itself isn’t deleted. It stays visible in your dashboard, marked removed at the commit that removed it, so “where did this go?” has an answer. See Deleting a published file for the detail.

Distributing to several of your own repos, with no team involved. --account subscribes your account instead of one repo, so every checkout you touch, this machine and the next one, gets it too:

mossbear pull team-skills --account

A branch or PR experiment. Publishing isn’t restricted by branch. Commit to a feature branch and run mossbear publish from it. The published revision records that branch and commit, so a subscriber can tell it’s a preview rather than main. Merge and publish again once it’s real.

A bundle someone outside your workspace maintains. The design target here is a read-only subscription with visible provenance. You never gain write access, and updates arrive only when the source publishes again. That collaboration surface doesn’t exist yet. Today, using an external source means someone in your workspace copies it into a repo they control and publishes it from there like any other team pack.

Moving between the two

Promotion is the one deliberate crossing, and it’s three steps, not one:

mossbear promote <path> → review the diff → commit → mossbear publish

mossbear promote previews the exact files it would write, asks you to confirm (or takes --yes in a script), and writes no commit itself. Run it with no path to see what’s promotable. Mossbear is still the source of truth until you commit. Promoting a draft doesn’t hand it to git; committing and publishing it does.

See Context layer for how bundles, the capture inbox, and the mossbear mcp server fit together, and CLI reference for every flag on the commands above.