Scopes and Project Discovery

Scopes and Project Discovery

Language: English · 简体中文

Scope determines which Wiki a command may read or mutate. Project discovery turns the current directory into an explicit filesystem authority boundary; it is not a convenience alias for arbitrary paths. This page covers normal discovery, intentional overrides, and the path-safety rules that keep one project from reaching another.

Scope model

Scope	Store	Intended use
project	nearest authorized ancestor <root>/.lwc/wiki.db	Repository knowledge and project operations
global	current user's ~/.lwc/wiki.db	Cross-project memory and defaults
all	bounded merge of initialized project and global stores	Read-oriented search, context, tag listing, and strong-tag loading

Mutating domain commands accept only project or global. When a read-oriented command offers a recording option, choose one explicit writable scope before enabling recording.

Project and global results retain their scope field after a merged read. LWC does not merge their canonical databases.

Normal project discovery

Run lwc from the project or one of its subdirectories:

cd /path/to/project
lwc --scope project context --limit 20

LWC walks ancestors from the current directory and selects the nearest real .lwc/wiki.db. It does not mistake the user's global ~/.lwc/wiki.db for a project Wiki and does not search above the user-home boundary.

lwc init reuses the nearest existing ancestor Wiki. If none exists, it initializes the current directory.

This behavior means routine commands need neither an exported project root nor an absolute binary variable.

Explicit LWC_PROJECT_ROOT

Use LWC_PROJECT_ROOT only when one process intentionally targets a known project boundary while its current directory is inside that boundary:

LWC_PROJECT_ROOT=/path/to/project lwc --scope project context --limit 20

LWC canonicalizes the root and current directory, then requires the current directory to remain inside the root. Resolution stops at that boundary.

If multiple project Wikis exist between the current directory and the explicit root, LWC returns project_scope_conflict instead of guessing which one owns the command.

Do not export this variable in shell startup files or Agent instructions. In the current project it adds noise and can make later commands target an unintended boundary.

Global home resolution

LWC resolves the user home through platform-appropriate variables in this order:

1. HOME;
2. USERPROFILE;
3. HOMEDRIVE plus HOMEPATH.

An unavailable home returns home_not_set. Agent installations and global Wiki operations use the same user boundary but their host-specific paths remain owned by each AgentTarget adapter.

Path safety

Store discovery validates the .lwc directory, wiki.db, WAL, and shared-memory sidecars as real paths. Symbolic links or non-regular files return a typed unsafe-path error.

When LWC_PROJECT_ROOT is explicit, every existing ancestor of a target path is canonicalized and must remain under the root. A symlink that resolves outside becomes project_root_escape.

Draft runtime, Work, graph sidecar, config, checkpoint, and materialization code repeat ownership checks at their own write boundaries. One early string-prefix check is not considered sufficient.

Source and conversion paths

Source manifests and conversion inputs normally remain inside the selected project. External Source or conversion input requires an explicit command option and still undergoes file-type, size, UTF-8, and secret checks.

Conversion output must be project-contained, must end in .md, and uses create-new semantics. Adapter arguments cannot smuggle an alternate output or positional filesystem path.

CodeGraph arguments are normalized relative to the canonical project and reject paths that escape through .., an absolute external path, or a resolving symlink.

MCP project authority

lwc serve --mcp accepts an absolute project path from the client for each exploration call. The path must exist, resolve to a project rather than filesystem root, and contain or discover the requested Wiki/CodeGraph state.

The server validates mode and path before invoking either backend. It never changes current process scope, initializes a missing capability, or accepts a relative path as ambient authority.

Agent installation scopes

Agent --location global and --location local are integration locations, not Wiki scopes:

• global writes the host's official user configuration;
• local writes the current project's official host surfaces;
• neither enables the project Wiki, document graph, or CodeGraph automatically.

Receipts record exact paths and post-install hashes. Refresh and uninstall use that ownership, not broad deletion under a host directory.

Secret boundary

Do not store secrets in:

• Source content unless the Wiki is explicitly authorized for that data;
• Page bodies or strong tags;
• command --reason fields or recorded query wording;
• trans arguments;
• Agent instructions, Hook output, or MCP configuration.

LWC scans selected ingest and configuration inputs for likely credentials, but detection is a guardrail, not proof that content is safe. The user remains responsible for the selected project's data classification and filesystem permissions.

Common errors

• store_not_found: no Wiki exists in the selected scope.
• project_root_invalid: the explicit root is empty, missing, or not a directory.
• project_root_mismatch: current directory is outside the explicit root.
• project_root_escape: a selected path or ancestor resolves outside the root.
• project_scope_conflict: more than one Wiki exists inside the explicit boundary.
• store_path_invalid: Store or sidecar path is not a safe regular path.
• scope_not_supported: the command cannot use --scope all.

Do not work around these errors with symlinks or private absolute binary aliases. Move to the authorized project directory or correct the explicit boundary.

Acceptance

Before a mutation, confirm:

lwc --scope project context --limit 1
lwc --scope project config show

Check the returned database/config paths and scope. For a deliberately external project, also verify the canonical root and current directory relation before running the mutation.

Next: Supported Agent compatibility