init
Everything exported by guardlink/init, from the .d.ts files published in guardlink@2.7.1. See the entry points for the other subpaths, and use guardlink as a library for worked examples.
Interfaces
Section titled “Interfaces”IncludeScope
Section titled “IncludeScope”Properties
Section titled “Properties”InitOptions
Section titled “InitOptions”Properties
Section titled “Properties”| Property | Type | Description |
|---|---|---|
agentIds? |
string[] |
Agents whose instruction files this run may CREATE when they do not exist. Without it, init writes its block only into instruction files that already exist: GuardLink does not add files to a repository it was not asked to. |
dryRun? |
boolean |
Dry run — show what would be created without writing |
force? |
boolean |
Re-scaffold an already-initialized project: rewrite config, README, prompt, reference doc, .mcp.json and the agent instruction blocks. It does NOT overwrite authored content. A definitions file holding declarations the template does not, and a config.json carrying settings the template does not, are preserved and reported (D24). Use reset for those. |
mode? |
AnnotationMode |
Where annotations LIVE. Nothing else. external (default) — .gal sidecars under .guardlink/annotations/ inline — comments in the source files themselves This used to also decide whether init wrote anything outside .guardlink/, which conflated two unrelated questions and made “keep annotations out of my source” cost you MCP auto-discovery and every agent instruction file — the two things that make an agent aware GuardLink exists at all. That footprint question is now rootFiles (GL-506). |
model? |
ThreatModel | null |
The model as parsed before init ran, when the caller has one. Decides the block’s opening (a repository being re-initialised may already have annotations) and its provenance stamp. Without it the stamp is computed for an empty annotation set, which is what a first init describes. |
project? |
string |
Override project name |
refreshScope? |
boolean |
Rewrite include in an existing config.json from the languages present now, leaving every other key as it is. Without it an existing config is never touched for scope: its include may be one a person chose. |
reset? |
boolean |
Overwrite authored content too — the definitions file and a customised config.json. This DESTROYS the threat model’s declarations. Typing the flag is the confirmation; there is no prompt, because the flag exists so the destructive intent has to be stated separately from “re-scaffold”. Implies force. |
root |
string |
Project root directory |
rootFiles? |
boolean |
Whether init may write outside .guardlink/. Default true: root .mcp.json, agent instruction files, docs/, .gitignore and .gitattributes. Set false for a zero-footprint install where .guardlink/ is the entire diff — what --mode external used to imply, now asked for on its own. |
skipAgentFiles? |
boolean |
Skip agent file updates (only create .guardlink/) |
InitResult
Section titled “InitResult”Properties
Section titled “Properties”| Property | Type | Description |
|---|---|---|
created |
string[] |
- |
preserved |
string[] |
Files --force declined to overwrite because they hold authored content (D24). Distinct from skipped, which is the ordinary “exists, not forcing” case: an entry here means the user asked for an overwrite and did not get one, so callers are expected to say so loudly. |
project |
ProjectInfo |
- |
scope |
IncludeScope |
The include scope detected for this repository, and why. |
scopeMissing |
string[] |
Globs the detected scope has that an existing, untouched config.json include lacks — languages present that the config does not parse. Empty when the scope was written or nothing is missing. |
scopeRefreshOnly |
boolean |
True when the only write to config.json was refreshScope’s. |
scopeWritten |
boolean |
Whether scope.include is what config.json now holds — it was created, re-scaffolded or refreshed by this run. False when an existing include was left alone. |
skipped |
string[] |
- |
updated |
string[] |
- |
SyncOptions
Section titled “SyncOptions”Properties
Section titled “Properties”| Property | Type |
|---|---|
dryRun? |
boolean |
model |
ThreatModel | null |
root |
string |
SyncResult
Section titled “SyncResult”Properties
Section titled “Properties”| Property | Type |
|---|---|
skipped |
string[] |
updated |
string[] |
Variables
Section titled “Variables”AGENT_CHOICES
Section titled “AGENT_CHOICES”
constAGENT_CHOICES:AgentChoice[]
Functions
Section titled “Functions”blockStamp()
Section titled “blockStamp()”blockStamp(
root,model):ModelContextFreshness
The provenance stamp for a block written now: the annotation hash of
model (of an empty annotation set when there is none yet, which is what a
first init describes) and the hash of what the repository’s agent
configuration grants, unless reading it is switched off.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
root |
string |
model |
ThreatModel | null |
Returns
Section titled “Returns”ModelContextFreshness
describeScope()
Section titled “describeScope()”describeScope(
scope,maxExcluded?):string[]
The lines init prints to explain the scope it wrote.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
scope |
IncludeScope |
maxExcluded? |
number |
Returns
Section titled “Returns”string[]
detectIncludeScope()
Section titled “detectIncludeScope()”detectIncludeScope(
root,primary):IncludeScope
The include for root: every language present that GuardLink parses.
primary is the language the root manifest names. It is always in scope even
with no files yet — a freshly created project keeps the include it had — and
when nothing parseable is found and no manifest names a language, the old
multi-language fallback stands.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
root |
string |
primary |
ProjectLanguage |
Returns
Section titled “Returns”initProject()
Section titled “initProject()”initProject(
options):InitResult
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
options |
InitOptions |
Returns
Section titled “Returns”promptAgentSelection()
Section titled “promptAgentSelection()”promptAgentSelection(
agentFiles):Promise<string[]>
Show detection-aware prompt. Displays:
- Always-created files
- Auto-detected agents (from directory presence)
- Optional agents user can add
Returns combined list of agent IDs (detected + user-selected).
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
agentFiles |
AgentFile[] |
Returns
Section titled “Returns”Promise<string[]>
replaceOrAppend()
Section titled “replaceOrAppend()”replaceOrAppend(
existing,block):string
If markers exist, replace the content between them. Otherwise append to end of file.
The rule, in every file init and sync write into: text outside the
markers is preserved byte for byte. Only the block between
<!-- guardlink:begin --> and <!-- guardlink:end -->, and the one line
break that ends it, are GuardLink’s — except a note another tool appended
after GuardLink’s footer line inside the block, which is carried forward
(see carryFooterTail).
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
existing |
string |
block |
string |
Returns
Section titled “Returns”string
resolveAgentFiles()
Section titled “resolveAgentFiles()”resolveAgentFiles(
agentIds):AgentChoice[]
Resolve agent IDs (from picker or flags) to file paths.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
agentIds |
string[] |
Returns
Section titled “Returns”AgentChoice[]
syncAgentFiles()
Section titled “syncAgentFiles()”syncAgentFiles(
options):SyncResult
Rewrite the stamped GuardLink block in every agent instruction file that exists.
Called after parse/validate/annotate to keep instructions up to date.
Uses marker-based replacement so text outside the markers is preserved byte
for byte, in every file — .cursor/rules/guardlink.mdc included.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
options |
SyncOptions |
Returns
Section titled “Returns”References
Section titled “References”AgentFile
Section titled “AgentFile”Re-exports AgentFile
detectProject
Section titled “detectProject”Re-exports detectProject
ProjectInfo
Section titled “ProjectInfo”Re-exports ProjectInfo

