Capability Configuration

Capability Configuration

Language: English · 简体中文

LWC capability configuration selects optional document-graph and Markdown-conversion behavior. It is layered, deployment-local state; it does not belong to Wiki knowledge or a changeset. Use this page to decide what to enable, where to configure it, and how to verify the effective result.

Both capabilities default to disabled. Initialization recommends available choices but never enables or installs one automatically.

Inspect effective configuration

lwc --scope project config show
lwc --scope global config show

The response contains:

• selected scope and config file path;
• effective graph setting and origin;
• effective trans setting, origin, timeout_seconds, anydoc_args, and markitdown_args.

Always inspect the effective value and origin. Reading only .lwc/config.json misses global inheritance and built-in defaults.

Layering

Resolution order is:

built-in disabled
      -> global config when not inherit
            -> project config when not inherit

Scope	Configuration path	Meaning
Global	~/.lwc/config.json	Cross-project default for the current user
Project	<project>/.lwc/config.json	Override for the selected project Wiki

Graph and trans layers resolve independently. A project can inherit global graph configuration while choosing its own conversion engine.

Config files use format version 3, reject unknown fields, validate values before replacement, and are written through an atomic temporary file. Symlinked config paths are rejected.

Document graph

Supported settings:

Value	Behavior
disabled	No external document-graph projection or query
grafeo	Use the embedded Grafeo file-backed engine
surrealdb	Use the embedded SurrealDB/SurrealKV engine
inherit	Use the next lower configuration layer

Enable one engine explicitly:

lwc --scope project config set --graph grafeo
lwc --scope project work watch <work-id>
lwc --scope project graph verify

Setting grafeo or surrealdb queues a full projection Work. Configuration success alone does not prove graph readiness.

Disable the capability without deleting canonical graph facts:

lwc --scope project config set --graph disabled

Restore inheritance:

lwc --scope project config unset --graph

unset changes the layer; it does not return graph Work. If the effective engine changes from disabled to enabled through inheritance, inspect graph status and graph verify. Use an explicit config set --graph <engine> to queue a full projection when a rebuild is required.

Do not switch engines while an earlier graph Work is active. Wait, verify, change the setting, then wait and verify the new engine independently.

Document conversion

Supported trans settings are disabled, markitdown, and anydoc:

lwc --scope project config set --trans markitdown
lwc --scope project config set --trans anydoc
lwc --scope project config set --trans disabled

Selecting an engine does not install it. lwc trans checks that the executable exists and returns a typed setup error when unavailable.

The default timeout is 120 seconds; accepted values are 1 through 900:

lwc --scope project config set \
  --trans markitdown \
  --trans-timeout 300

Repeated --trans-arg values replace the selected engine's stored argument list:

lwc --scope project config set \
  --trans markitdown \
  --trans-timeout 300 \
  --trans-arg --keep-data-uris

Arguments for the other engine remain stored separately. Selecting disabled does not accept arguments.

Config writes reject explicit credential flags and values that look like secrets. Runtime conversion performs another safety check for path-like positional arguments, output overrides, credential flags, and other arguments that could escape LWC's ownership boundary.

Do not store API keys, tokens, passwords, subscription keys, or customer secrets in trans arguments.

Restore the trans layer to inherited defaults:

lwc --scope project config unset --trans

Atomic combined update

Graph and trans settings can change in one config replacement:

lwc --scope project config set \
  --graph grafeo \
  --trans markitdown \
  --trans-timeout 300

If the graph selection is explicit and enabled, the response also returns projection Work. Watch it even when the conversion setting was the primary reason for the command.

Scope rules

• project updates <project>/.lwc/config.json.
• global updates ~/.lwc/config.json.
• all is rejected.
• A changeset selector is rejected because configuration is deployment-local.
• Project discovery comes from the current directory unless one command intentionally uses LWC_PROJECT_ROOT.

Do not export LWC_PROJECT_ROOT or define a private LWC=/path/to/lwc variable for routine use. Install lwc on PATH and run it from the project.

Safe editing rule

Use lwc config set and lwc config unset. Do not hand-edit JSON during an active process. A malformed file blocks resolution with invalid_config; an unsupported version returns unsupported_config_version.

If a config file must be reviewed by policy, use config show for the effective contract and inspect the owned file read-only. Redact arguments before sharing diagnostics.

Acceptance

After any configuration change:

1. run config show and confirm setting plus origin;
2. watch returned Work;
3. verify the enabled graph independently;
4. for trans, perform one non-sensitive real conversion and inspect its receipt and output;
5. confirm no secret was persisted;
6. record configuration separately from canonical Wiki changes.

Next: Scope, project resolution, and security