@spec absolute_path(PhoenixKitKnowledgeBase.Schemas.Vault.t()) :: String.t()

Absolute path to a vault's directory, for showing the operator where its files are.

@spec can?(String.t() | nil, :read | :write | :manage) :: boolean()

Whether a role permits an action.

• :read — viewer and up
• :write — editor and up (notes, folders)
• :manage — owner only (membership, vault settings, deletion)

@spec can_manage_system_vaults?(PhoenixKit.Users.Auth.Scope.t() | nil) :: boolean()

Whether this user may create system vaults (as opposed to personal ones).

@spec change(PhoenixKitKnowledgeBase.Schemas.Vault.t(), map()) :: Ecto.Changeset.t()

A blank changeset for the create/edit form.

@spec create(map(), PhoenixKit.Users.Auth.Scope.t() | nil, :user | :system) ::
  {:ok, PhoenixKitKnowledgeBase.Schemas.Vault.t()}
  | {:error, Ecto.Changeset.t()}
  | {:error, :unauthorized}
  | {:error, term()}

Create a vault owned by this user.

scope_kind is :user for a personal vault or :system for an org-wide one; :system is rejected without knowledge_base.manage_system_vaults, here rather than only in the UI, so the check can't be skipped by a crafted form submission.

@spec delete(PhoenixKitKnowledgeBase.Schemas.Vault.t()) ::
  {:ok, PhoenixKitKnowledgeBase.Schemas.Vault.t()}
  | {:error, Ecto.Changeset.t()}

Remove a vault from the app.

Deletes the vault row and, by FK cascade, its members and its whole index — but not the files. Notes are the durable artifact here; a mis-click in a web UI should not be able to rm -rf somebody's writing. The directory stays on disk, and re-creating a vault with the same slug and pressing Rescan brings every note back.

@spec fetch_for(String.t(), PhoenixKit.Users.Auth.Scope.t() | nil) ::
  {:ok, PhoenixKitKnowledgeBase.Schemas.Vault.t(), String.t()}
  | {:error, :not_found}

Fetch a vault for a user, resolving their role in the same step.

{:error, :not_found} covers both "no such slug" and "you may not see it" — telling those apart would leak the existence of other people's vaults.

@spec get(String.t()) :: PhoenixKitKnowledgeBase.Schemas.Vault.t() | nil

Fetch a vault by uuid, or nil. Returns nil for a malformed uuid rather than raising.

@spec get_by_slug(String.t()) :: PhoenixKitKnowledgeBase.Schemas.Vault.t() | nil

Fetch a vault by its URL slug, or nil.

@spec get_member(PhoenixKitKnowledgeBase.Schemas.Vault.t(), String.t()) ::
  PhoenixKitKnowledgeBase.Schemas.VaultMember.t() | nil

Fetch a membership row scoped to its vault, or nil.

@spec list_members(PhoenixKitKnowledgeBase.Schemas.Vault.t()) :: [
  %{member: PhoenixKitKnowledgeBase.Schemas.VaultMember.t(), user: map() | nil}
]

Members of a vault with their user records, owners first.

The user is loaded by a join rather than a preload because PhoenixKit.Users.Auth.User belongs to core: joining on uuid uses the documented schema contract without this module declaring an association into another package's schema.

@spec list_visible(PhoenixKit.Users.Auth.Scope.t() | nil) :: [
  PhoenixKitKnowledgeBase.Schemas.Vault.t()
]

Every vault this user may open, system vaults first, then alphabetical.

Runs as one query rather than a filter over all vaults, so a host with many personal vaults doesn't load them all to throw most away.

@spec list_visible_with_roles(PhoenixKit.Users.Auth.Scope.t() | nil) :: [
  {PhoenixKitKnowledgeBase.Schemas.Vault.t(), String.t()}
]

list_visible/1 with each vault's role resolved, as {vault, role}.

One membership query for the whole list rather than role_for/2 per vault — the list page would otherwise issue a query per card.

@spec manage_system_permission() :: String.t()

The sub-permission key that confers ownership of every system vault.

@spec put_member(PhoenixKitKnowledgeBase.Schemas.Vault.t(), String.t(), String.t()) ::
  {:ok, PhoenixKitKnowledgeBase.Schemas.VaultMember.t()}
  | {:error, Ecto.Changeset.t()}

Add a user to a vault, or change their role if already a member.

@spec remove_member(PhoenixKitKnowledgeBase.Schemas.VaultMember.t()) ::
  {:ok, PhoenixKitKnowledgeBase.Schemas.VaultMember.t()}
  | {:error, Ecto.Changeset.t()}

Remove a membership row. The implicit owner of a personal vault is unaffected.

@spec role_for(
  PhoenixKitKnowledgeBase.Schemas.Vault.t(),
  PhoenixKit.Users.Auth.Scope.t() | nil
) ::
  String.t() | nil

The role scope's user holds on vault, or nil if they cannot see it.

Takes the highest of the implicit roles and any membership row, so being added as a viewer of a system vault you already administer does not reduce your access.

@spec role_label(String.t() | nil) :: String.t()

A role, for showing — the stored value stays English (owner / editor / viewer).

@spec search_candidates(PhoenixKitKnowledgeBase.Schemas.Vault.t(), String.t()) :: [
  map()
]

Users matching term who are not already members, for the "add member" picker. Delegates the search to core so it stays consistent with the rest of the admin.

@spec update(PhoenixKitKnowledgeBase.Schemas.Vault.t(), map()) ::
  {:ok, PhoenixKitKnowledgeBase.Schemas.Vault.t()}
  | {:error, Ecto.Changeset.t()}

Update a vault's name, slug, description or icon. Scope and owner are fixed at creation.

@spec user_label(map() | nil) :: String.t()

A display label for a user record from search_candidates/2 or list_members/1.