ingest

---
name: ingest
description: Research a repository or directory and author grounded OKF v0.2 concepts with standard provenance. Use for source-code or mixed-artifact research; use migrate for pre-written docs and init for an empty bundle.
---

# Research and ingest a repository

Use `okf source-scan <directory>` when an inventory is needed, scoped to the relevant source
directory. Use normal code-search tools on that external source, but query existing bundle content
through the CLI and retrieve only targeted slices.


## CLI compatibility preflight

Before CLI-dependent work, run `sh <this-skill-directory>/../../scripts/check-cli.sh`,
resolving the path from this installed SKILL.md, not the working directory. This read-only
check uses the plugin's `cli-compatibility.txt` range and reports the executable on PATH.
If missing, incompatible, or unable to run, stop CLI-dependent work and show its installation
instructions. Never invoke the installer, download a CLI, or update it from this skill.
An explicit user request to install should be handled separately from this workflow.
Only after this check passes may command help resolve syntax differences; help cannot waive
compatibility. Recheck if the executable or PATH changes during the task.

## CLI and output rules

Prefer `OKF_BUNDLE` during multi-step work; one explicit form is `okf edit <concept-id> <bundle>
--add-source resource=<path>`. Before using an unfamiliar command or flag, read its entry in
`references/cli.md`. If the installed version differs or rejects documented syntax, use that
command's `--help` output as the runtime authority.

Producer rubric:

- Conformance requires parseable frontmatter, non-empty `type`, and valid reserved files.
- Recommended fields are `title`, `description`, applicable `resource`, `tags`, structured Markdown,
  and absolute bundle-relative concept links.
- Provenance, trust, lifecycle, and computation families are optional with defined semantics.
- Ontology and source `kind`/`fingerprint` are tool extensions, never conformance requirements.

## Workflow

1. Start from the requested subsystem or files. Use `okf source-scan <source-directory> --json` when
   their extent is unclear; a full repository scan is unnecessary for a narrow request. The scan
   inventories paths and sizes, not content or secret classifications. Filter its results before
   reading/storing material; exclude secrets and irrelevant generated output.
2. Research meaningful concepts rather than producing one concept per file. Ground every claim in
   inspected evidence. Use an ontology only as advisory classification; unknown types remain valid
   OKF.
3. Search the target for existing concepts using `okf search <bundle> --text "topic" --limit 10` and
   inspect plausible matches. Resolve bundle identity/scope before searching; consult each selected
   bundle's effective ontology when authoring structured fields. Check scan warnings before deciding
   there is no existing equivalent: an incomplete scan requires a sufficient `--scan-limit`, a
   deliberate `--full-scan`, or an explicitly unresolved duplicate check. `--limit` does not bound
   scan work. Update an existing concept when appropriate; do not duplicate it. Stop
   research when the requested concepts and their material claims have adequate evidence; report
   unresolved points rather than expanding to unrelated subsystems. Add new concepts with `okf add
   <path> <bundle> --type <Type> --body @/tmp/concept-body.md` (Markdown body only, no
   frontmatter). This creates content in one write and leaves no skeleton if the input is unreadable.
   When generation provenance is enabled, pass `--generated-by <actor>`; the CLI supplies the
   explicit-offset timestamp.
4. Add standard sources with `okf edit <concept-id> <bundle> --add-source
   "resource=<path>,id=source-1"`. For a full source mapping, use `okf edit <concept-id> <bundle>
   --add-source-json @/tmp/source.yaml`. Each entry needs `resource`; use stable `id` values and
   matching Markdown footnotes for per-claim attribution. Add credibility or usage fields only from
   evidence. `kind`/`fingerprint` may be added for local drift tracking. Having sources is a
   recommended ingest policy when known, not an OKF conformance rule.
5. For nested metadata, use the ontology skill's
   [structured authoring example](../ontology/references/structured-authoring.md) and preserve
   current provenance with `--set-yaml`, object `--set-path`, or concrete `--patch` operations. Cross-bundle
   source mappings follow the init skill's [catalog example](../init/references/multi-bundle.md),
   including separate-repository layouts. Qualified catalog IDs are CLI targets; author body and
   custom metadata concept links as ordinary paths that match the checkout layout.
   Use direct Markdown links for portable relationships. Ontology reference fields may add a local
   typed view but must not replace standard links or source lineage. Spot-check authored edges with
   `okf links <concept-id> <bundle> --json` so normalized targets and missing concepts are visible
   without traversing the whole graph.
6. Only for a requested computation, use exact `Attested Computation` with `okf add <path> <bundle>
   --attested --runtime <runtime>`. Read the add/computation sections of `references/cli.md` for
   parameters, inline/file forms, and contract resources. Inspect with `okf computation check
   <concept-id> <bundle>`; this does not execute or attest a run.
7. Run `okf validate <bundle>`, advisory `okf lint <bundle> --fail-on never`, and use `okf docs
   <bundle> --format index` only when index bodies are generated or replacement is already
   authorized. It overwrites index prose throughout the bundle; preserve curated indexes otherwise.
   Validate after generating indexes.

When local fingerprint tracking is enabled with a source `kind`, review its evidence and run
`okf refresh <concept-id> <bundle> --fail-on skipped` to record the baseline. `okf stale <bundle>
--fail-on any` distinguishes `unrecorded` (no baseline), `missing` (cannot fingerprint), and
`drifted` (changed baseline). Standard kind-less provenance is not fingerprint-checked. Inspect
findings even when a command succeeds: stale defaults to a successful exit on findings, and
`lint --fail-on never` is reporting only. Use `okf lint <bundle> --fail-on warn` when source warnings
must fail a health gate; conformance validation alone does not establish source health.

## Source locations

`references/` is an optional location for authorized copies; Markdown files are concepts and other
files are artifacts. Preserve the external origin. Repository-relative fingerprint paths and
bundle/document-relative artifact paths use different roots: read the artifact resolution notes in
`references/cli.md` before choosing `sources[].resource` and `kind`. Use `okf artifact resolve
<resource> <bundle> --from <concept-id>` and bounded `okf artifact show` for bundle artifacts.
Inspect authorized external repository sources with normal source tools; do not change provenance or
copy them merely to bypass a blocked artifact read. Inspection is not permission to execute code.

For an authorized artifact copy or authored schema, use `okf artifact put
contracts/x/references/schema.json @/tmp/schema.json <bundle>`. The destination is bundle-relative;
the input file is relative to cwd. Creation is the default; use `--replace` only for an intended
replacement. Writes preserve recorded fingerprints, so review citing concepts before refreshing
them. This command does not execute artifacts or grant permission to copy external material.

Report created/updated/skipped concepts, source evidence, validation, and any unresolved scope.
Include optional extensions or copied artifacts only when used.

## Bundle identity and examination scope

Keep bundle paths and catalog IDs distinct. `OKF_BUNDLE` always selects a path; use the
`--bundle-id <id>` for a registered identity. When a catalog is configured, use `okf catalog` to inspect effective local
registrations, overrides, availability, and per-bundle settings. Catalog paths are relative to
`okf.toml`, locations are relative to the catalog, and machine-local overrides change effective
locations rather than accepting different snapshots. Inspect effective settings before relying on
a per-bundle ontology or view. Equal or nested registered roots are configuration errors.

Registration alone does not authorize catalog-wide traversal. Start with the selected bundle;
request additional bundles explicitly with repeatable `--scope-bundle <id>` or deliberate
`--catalog-scope` when the task requires them. Report requested and examined
scope and unavailable members. Out-of-scope references remain unknown. Ordinary relative paths
retain their meaning across registered boundaries; distributing one bundle alone can break them.
Never infer another bundle from a matching filename or title.

## Source baseline lint configuration

`source-unrecorded` defaults to `warn`. If the user wants a different policy, configure
`source_unrecorded = "off"`, `"info"`, `"warn"`, or `"error"` under
`[bundle_settings.default.lint]` in `okf.toml` (or `[bundle_settings."<id>".lint]`
for a named bundle). `off` suppresses this lint finding only; missing-source errors
(default `error`, independently configurable via `source_missing`) and `stale` findings remain active. Do not suppress findings merely to pass a gate.

All lint rule settings accept `off`, `info`, `warn`, or `error` in the same table.
Defaults: `broken_link` and `source_missing` are `error`; `missing_title`, `spec_v02`
(finding rule `okf-v02`), `ontology_violation`, `source_unrecorded`, and `index_coverage`
are `warn`; `missing_description` and `orphan` are `info`. Omitted settings keep these
severities. Turning a lint rule off does not change conformance validation or stale checks.

## Frontmatter order

When authoring concept frontmatter, put `type` first. For the matching ontology concept type,
follow `fields` declaration order recursively, including nested objects and objects in lists;
reusable field types use their resolved field order. Put reference-only keys next in reference
declaration order. Put undeclared/custom fields last at each level, preserving their relative
order. Without a matching ontology type, keep the other fields in their authored order.
This is an authoring convention, not an additional OKF conformance requirement.
CLI writes normalize this order. `okf lint <bundle>` reports `frontmatter-order` at warning by
default; `okf lint <bundle> --fix` normalizes the bundle and reports remaining findings. The
bundle lint setting `frontmatter_order` accepts `info`, `warn`, `error`, or `off`; an off rule
is not fixed. Normalization preserves values, list order, body text, and verification metadata;
YAML comments and scalar presentation may normalize.

• SKILL.md 11 KB
• references/cli.md 33 KB