Overview
Approved-alternative library policies let your organization say, for each workspace, "prefer
package B over package A." When an AI assistant or agent asks the Vibgrate library for
documentation about the package you're moving away from — and the request opts into strict mode
(enterprise_strict) — your approved package's documentation leads the answer, with a short note
explaining the preference.
The result: agents write code against the dependency you've blessed, not the one you're retiring — without anyone hand-editing prompts or context.
What a policy captures
Each policy is a simple, reviewable statement:
| Field | Meaning |
|---|---|
| Banned | the package to steer away from — ecosystem, name, and an optional version |
| Approved | the package to steer toward — ecosystem, name, and an optional version |
| Relationship | approved alternative (recommend instead) or replaces (a successor) |
| Reason | an optional, human-readable rationale shown alongside the recommendation |
Example: prefer dayjs over moment on npm, because moment is in maintenance mode.
Where to manage them
Library policies live in the platform's Policies section, right next to your other policies — they are not a separate tool. They show up in the same policy list, activity feed, and audit trail, so governance stays in one place.
From there you can create, edit, enable, disable, and delete a policy. A policy only takes effect while it is enabled.
Who can manage them
Library policies follow the same role-based access control (RBAC) as every platform policy:
| Permission | Grants |
|---|---|
View policies (policy:read) | see policies and their history |
Manage policies (policy:write) | create, edit, enable/disable, and delete policies |
Members and viewers can read policies; owners and admins can manage them. Anyone without the manage permission sees policies read-only. Every create, edit, and delete is recorded in the workspace audit log, so each change is traceable to the person who made it.
What strict mode does
When an agent requests library documentation in strict mode for the banned package, the answer:
- leads with the approved package's documentation, and
- includes a short remediation note naming the preferred package and your reason.
Policies are tenant-isolated: a policy you set only ever affects your workspace's strict-mode results. It never affects another organization, and it never changes the public catalog.
Enforce the same choice in CI
Hosted policies steer the assistant; to fail a build on a banned dependency, pair them with the local, offline gate — commit your approved/banned choices and run:
vg drift --fail-on standards
The command exits non-zero with remediation when a banned package is found, so the same governance holds in your pipeline. See Supply Chain and the Dashboard for related capabilities.