@interf/compiler 0.2.4 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (240) hide show
  1. package/README.md +194 -148
  2. package/dist/commands/benchmark.d.ts.map +1 -1
  3. package/dist/commands/benchmark.js +60 -351
  4. package/dist/commands/benchmark.js.map +1 -1
  5. package/dist/commands/compile.d.ts.map +1 -1
  6. package/dist/commands/compile.js +43 -110
  7. package/dist/commands/compile.js.map +1 -1
  8. package/dist/commands/create-workflow-wizard.d.ts +4 -25
  9. package/dist/commands/create-workflow-wizard.d.ts.map +1 -1
  10. package/dist/commands/create-workflow-wizard.js +29 -214
  11. package/dist/commands/create-workflow-wizard.js.map +1 -1
  12. package/dist/commands/create.d.ts +2 -11
  13. package/dist/commands/create.d.ts.map +1 -1
  14. package/dist/commands/create.js +72 -455
  15. package/dist/commands/create.js.map +1 -1
  16. package/dist/commands/default.d.ts.map +1 -1
  17. package/dist/commands/default.js +16 -28
  18. package/dist/commands/default.js.map +1 -1
  19. package/dist/commands/init.d.ts.map +1 -1
  20. package/dist/commands/init.js +71 -337
  21. package/dist/commands/init.js.map +1 -1
  22. package/dist/commands/list.d.ts.map +1 -1
  23. package/dist/commands/list.js +12 -22
  24. package/dist/commands/list.js.map +1 -1
  25. package/dist/commands/reset.d.ts.map +1 -1
  26. package/dist/commands/reset.js +27 -124
  27. package/dist/commands/reset.js.map +1 -1
  28. package/dist/commands/source-config-wizard.d.ts +13 -6
  29. package/dist/commands/source-config-wizard.d.ts.map +1 -1
  30. package/dist/commands/source-config-wizard.js +93 -59
  31. package/dist/commands/source-config-wizard.js.map +1 -1
  32. package/dist/commands/status.d.ts.map +1 -1
  33. package/dist/commands/status.js +60 -56
  34. package/dist/commands/status.js.map +1 -1
  35. package/dist/commands/verify.d.ts.map +1 -1
  36. package/dist/commands/verify.js +59 -98
  37. package/dist/commands/verify.js.map +1 -1
  38. package/dist/index.d.ts +7 -7
  39. package/dist/index.d.ts.map +1 -1
  40. package/dist/index.js +4 -6
  41. package/dist/index.js.map +1 -1
  42. package/dist/lib/agent-constants.js +1 -1
  43. package/dist/lib/agent-constants.js.map +1 -1
  44. package/dist/lib/benchmark-execution.d.ts.map +1 -1
  45. package/dist/lib/benchmark-execution.js +7 -16
  46. package/dist/lib/benchmark-execution.js.map +1 -1
  47. package/dist/lib/benchmark-targets.d.ts +3 -4
  48. package/dist/lib/benchmark-targets.d.ts.map +1 -1
  49. package/dist/lib/benchmark-targets.js +9 -55
  50. package/dist/lib/benchmark-targets.js.map +1 -1
  51. package/dist/lib/benchmark-types.d.ts +2 -3
  52. package/dist/lib/benchmark-types.d.ts.map +1 -1
  53. package/dist/lib/benchmark.d.ts +1 -1
  54. package/dist/lib/benchmark.d.ts.map +1 -1
  55. package/dist/lib/benchmark.js +1 -1
  56. package/dist/lib/benchmark.js.map +1 -1
  57. package/dist/lib/config.d.ts +1 -2
  58. package/dist/lib/config.d.ts.map +1 -1
  59. package/dist/lib/config.js +2 -4
  60. package/dist/lib/config.js.map +1 -1
  61. package/dist/lib/discovery.d.ts +1 -1
  62. package/dist/lib/discovery.d.ts.map +1 -1
  63. package/dist/lib/discovery.js +7 -2
  64. package/dist/lib/discovery.js.map +1 -1
  65. package/dist/lib/eval-packs.d.ts +6 -52
  66. package/dist/lib/eval-packs.d.ts.map +1 -1
  67. package/dist/lib/eval-packs.js +11 -39
  68. package/dist/lib/eval-packs.js.map +1 -1
  69. package/dist/lib/interf-bootstrap.d.ts +3 -5
  70. package/dist/lib/interf-bootstrap.d.ts.map +1 -1
  71. package/dist/lib/interf-bootstrap.js +10 -57
  72. package/dist/lib/interf-bootstrap.js.map +1 -1
  73. package/dist/lib/interf-detect.d.ts +13 -11
  74. package/dist/lib/interf-detect.d.ts.map +1 -1
  75. package/dist/lib/interf-detect.js +59 -45
  76. package/dist/lib/interf-detect.js.map +1 -1
  77. package/dist/lib/interf-scaffold.d.ts +2 -5
  78. package/dist/lib/interf-scaffold.d.ts.map +1 -1
  79. package/dist/lib/interf-scaffold.js +98 -235
  80. package/dist/lib/interf-scaffold.js.map +1 -1
  81. package/dist/lib/interf-workflow-package.d.ts +1 -2
  82. package/dist/lib/interf-workflow-package.d.ts.map +1 -1
  83. package/dist/lib/interf-workflow-package.js +94 -90
  84. package/dist/lib/interf-workflow-package.js.map +1 -1
  85. package/dist/lib/interf.d.ts +4 -5
  86. package/dist/lib/interf.d.ts.map +1 -1
  87. package/dist/lib/interf.js +3 -6
  88. package/dist/lib/interf.js.map +1 -1
  89. package/dist/lib/local-workflows.d.ts +9 -8
  90. package/dist/lib/local-workflows.d.ts.map +1 -1
  91. package/dist/lib/local-workflows.js +42 -94
  92. package/dist/lib/local-workflows.js.map +1 -1
  93. package/dist/lib/obsidian.d.ts +1 -5
  94. package/dist/lib/obsidian.d.ts.map +1 -1
  95. package/dist/lib/obsidian.js +11 -165
  96. package/dist/lib/obsidian.js.map +1 -1
  97. package/dist/lib/registry.d.ts +6 -17
  98. package/dist/lib/registry.d.ts.map +1 -1
  99. package/dist/lib/registry.js +36 -50
  100. package/dist/lib/registry.js.map +1 -1
  101. package/dist/lib/runtime-contracts.d.ts +2 -3
  102. package/dist/lib/runtime-contracts.d.ts.map +1 -1
  103. package/dist/lib/runtime-contracts.js +10 -9
  104. package/dist/lib/runtime-contracts.js.map +1 -1
  105. package/dist/lib/runtime-reconcile.d.ts +2 -5
  106. package/dist/lib/runtime-reconcile.d.ts.map +1 -1
  107. package/dist/lib/runtime-reconcile.js +23 -176
  108. package/dist/lib/runtime-reconcile.js.map +1 -1
  109. package/dist/lib/runtime-runs.d.ts.map +1 -1
  110. package/dist/lib/runtime-runs.js +52 -57
  111. package/dist/lib/runtime-runs.js.map +1 -1
  112. package/dist/lib/runtime-types.d.ts +5 -6
  113. package/dist/lib/runtime-types.d.ts.map +1 -1
  114. package/dist/lib/runtime.d.ts +2 -2
  115. package/dist/lib/runtime.d.ts.map +1 -1
  116. package/dist/lib/runtime.js +1 -1
  117. package/dist/lib/runtime.js.map +1 -1
  118. package/dist/lib/schema.d.ts +53 -312
  119. package/dist/lib/schema.d.ts.map +1 -1
  120. package/dist/lib/schema.js +39 -206
  121. package/dist/lib/schema.js.map +1 -1
  122. package/dist/lib/source-config.d.ts +7 -7
  123. package/dist/lib/source-config.d.ts.map +1 -1
  124. package/dist/lib/source-config.js +55 -62
  125. package/dist/lib/source-config.js.map +1 -1
  126. package/dist/lib/state-artifacts.d.ts +5 -11
  127. package/dist/lib/state-artifacts.d.ts.map +1 -1
  128. package/dist/lib/state-artifacts.js +8 -18
  129. package/dist/lib/state-artifacts.js.map +1 -1
  130. package/dist/lib/state-health.d.ts +4 -8
  131. package/dist/lib/state-health.d.ts.map +1 -1
  132. package/dist/lib/state-health.js +27 -223
  133. package/dist/lib/state-health.js.map +1 -1
  134. package/dist/lib/state-io.d.ts +7 -12
  135. package/dist/lib/state-io.d.ts.map +1 -1
  136. package/dist/lib/state-io.js +26 -93
  137. package/dist/lib/state-io.js.map +1 -1
  138. package/dist/lib/state-view.d.ts +4 -6
  139. package/dist/lib/state-view.d.ts.map +1 -1
  140. package/dist/lib/state-view.js +62 -101
  141. package/dist/lib/state-view.js.map +1 -1
  142. package/dist/lib/state.d.ts +5 -5
  143. package/dist/lib/state.d.ts.map +1 -1
  144. package/dist/lib/state.js +4 -4
  145. package/dist/lib/state.js.map +1 -1
  146. package/dist/lib/summarize-plan.d.ts +2 -2
  147. package/dist/lib/summarize-plan.d.ts.map +1 -1
  148. package/dist/lib/summarize-plan.js +13 -13
  149. package/dist/lib/summarize-plan.js.map +1 -1
  150. package/dist/lib/{validate-kb.d.ts → validate-workspace.d.ts} +8 -8
  151. package/dist/lib/validate-workspace.d.ts.map +1 -0
  152. package/dist/lib/{validate-kb.js → validate-workspace.js} +44 -46
  153. package/dist/lib/validate-workspace.js.map +1 -0
  154. package/dist/lib/validate.d.ts +5 -7
  155. package/dist/lib/validate.d.ts.map +1 -1
  156. package/dist/lib/validate.js +6 -19
  157. package/dist/lib/validate.js.map +1 -1
  158. package/dist/lib/workflow-definitions.d.ts +14 -50
  159. package/dist/lib/workflow-definitions.d.ts.map +1 -1
  160. package/dist/lib/workflow-definitions.js +74 -349
  161. package/dist/lib/workflow-definitions.js.map +1 -1
  162. package/dist/lib/workflow-helpers.d.ts +3 -4
  163. package/dist/lib/workflow-helpers.d.ts.map +1 -1
  164. package/dist/lib/workflow-helpers.js +15 -49
  165. package/dist/lib/workflow-helpers.js.map +1 -1
  166. package/dist/lib/workflow-stage-runner.d.ts +1 -2
  167. package/dist/lib/workflow-stage-runner.d.ts.map +1 -1
  168. package/dist/lib/workflow-stage-runner.js +4 -6
  169. package/dist/lib/workflow-stage-runner.js.map +1 -1
  170. package/dist/lib/workflow-starter-docs.d.ts +3 -5
  171. package/dist/lib/workflow-starter-docs.d.ts.map +1 -1
  172. package/dist/lib/workflow-starter-docs.js +2 -17
  173. package/dist/lib/workflow-starter-docs.js.map +1 -1
  174. package/dist/lib/workflows.d.ts +9 -14
  175. package/dist/lib/workflows.d.ts.map +1 -1
  176. package/dist/lib/workflows.js +13 -30
  177. package/dist/lib/workflows.js.map +1 -1
  178. package/dist/lib/workspace-compile.d.ts +50 -0
  179. package/dist/lib/workspace-compile.d.ts.map +1 -0
  180. package/dist/lib/{workflows-kb.js → workspace-compile.js} +81 -89
  181. package/dist/lib/workspace-compile.js.map +1 -0
  182. package/package.json +9 -9
  183. package/skills/benchmark/SKILL.md +16 -24
  184. package/skills/workflow/create/SKILL.md +7 -14
  185. package/templates/workspace/README.md +23 -0
  186. package/templates/workspace/interfignore +2 -0
  187. package/dist/lib/bundled-templates.d.ts +0 -5
  188. package/dist/lib/bundled-templates.d.ts.map +0 -1
  189. package/dist/lib/bundled-templates.js +0 -23
  190. package/dist/lib/bundled-templates.js.map +0 -1
  191. package/dist/lib/interf-compile-plan.d.ts +0 -12
  192. package/dist/lib/interf-compile-plan.d.ts.map +0 -1
  193. package/dist/lib/interf-compile-plan.js +0 -143
  194. package/dist/lib/interf-compile-plan.js.map +0 -1
  195. package/dist/lib/validate-interface.d.ts +0 -79
  196. package/dist/lib/validate-interface.d.ts.map +0 -1
  197. package/dist/lib/validate-interface.js +0 -535
  198. package/dist/lib/validate-interface.js.map +0 -1
  199. package/dist/lib/validate-kb.d.ts.map +0 -1
  200. package/dist/lib/validate-kb.js.map +0 -1
  201. package/dist/lib/workflows-interface-contracts.d.ts +0 -24
  202. package/dist/lib/workflows-interface-contracts.d.ts.map +0 -1
  203. package/dist/lib/workflows-interface-contracts.js +0 -304
  204. package/dist/lib/workflows-interface-contracts.js.map +0 -1
  205. package/dist/lib/workflows-interface.d.ts +0 -72
  206. package/dist/lib/workflows-interface.d.ts.map +0 -1
  207. package/dist/lib/workflows-interface.js +0 -377
  208. package/dist/lib/workflows-interface.js.map +0 -1
  209. package/dist/lib/workflows-kb.d.ts +0 -50
  210. package/dist/lib/workflows-kb.d.ts.map +0 -1
  211. package/dist/lib/workflows-kb.js.map +0 -1
  212. package/skills/interface/analyze/SKILL.md +0 -191
  213. package/skills/interface/compile/SKILL.md +0 -152
  214. package/skills/interface/compile/references/output-format.md +0 -48
  215. package/skills/interface/create/SKILL.md +0 -87
  216. package/skills/interface/create/references/compile-plan-format.md +0 -109
  217. package/skills/interface/create/references/workflows.md +0 -35
  218. package/skills/interface/query/SKILL.md +0 -48
  219. package/skills/interface/retrieve/SKILL.md +0 -133
  220. package/skills/knowledge-base/compile/SKILL.md +0 -196
  221. package/skills/knowledge-base/compile/references/output-format.md +0 -48
  222. package/skills/knowledge-base/compile/references/stage-claims.md +0 -60
  223. package/skills/knowledge-base/compile/references/stage-entities.md +0 -46
  224. package/skills/knowledge-base/query/SKILL.md +0 -45
  225. package/skills/knowledge-base/summarize/SKILL.md +0 -152
  226. package/templates/interface/README.md +0 -159
  227. package/templates/interface/interfaces.md +0 -102
  228. package/templates/knowledge-base/README.md +0 -137
  229. package/templates/knowledge-base/interfignore +0 -19
  230. package/templates/knowledge-base/registry.md +0 -118
  231. package/templates/workflow-package/README.md +0 -16
  232. package/templates/workflow-package/create/SKILL.md +0 -8
  233. package/templates/workflow-package/interface-query/SKILL.md +0 -29
  234. package/templates/workflow-package/interface-stage/SKILL.md +0 -13
  235. package/templates/workflow-package/knowledge-base-query/SKILL.md +0 -36
  236. package/templates/workflow-package/knowledge-base-stage/SKILL.md +0 -13
  237. package/templates/workflow-starters/interface/interf/README.md +0 -13
  238. package/templates/workflow-starters/interface/interf/create/SKILL.md +0 -15
  239. package/templates/workflow-starters/knowledge-base/interf/README.md +0 -13
  240. package/templates/workflow-starters/knowledge-base/karpathy/README.md +0 -13
@@ -1,152 +0,0 @@
1
- ---
2
- {
3
- "name": "knowledge-base/summarize",
4
- "description": "Generate summaries for unprocessed source files in a knowledge base. Reads interf.json for format rules. Creates one summaries/ file per source file with abstract, overview, metadata, and wikilinks. Use when asked to summarize, process files, generate summaries, or after adding new files to a knowledge base."
5
- }
6
- ---
7
-
8
- # Summarize Source Files into Summaries
9
-
10
- Read `interf.json`, `.interf/stage-contract.json`, and `.interf/run.json` first.
11
-
12
- Use only local workspace files for this run:
13
- - `interf.json`
14
- - `.interf/stage-contract.json`
15
- - `.interf/summarize-targets.json` when present
16
- - `.interf/source-access.json` when raw-file access needs a quick check
17
- - local instruction docs explicitly listed by `.interf/stage-contract.json`
18
-
19
- Do not open SDK repo docs or source files outside the current workspace. The local contract and local docs are the source of truth.
20
-
21
- Harness role:
22
- - This skill is normally invoked as one of the file-evidence stages inside `interf compile`.
23
- - When launched by the CLI, follow the stage contract exactly and keep user-visible output to `STATUS:`, `DONE:`, `BLOCKED:`, or `ERROR:` lines only.
24
-
25
- ## Required sequence
26
-
27
- 1. Read `interf.json` and confirm `type: knowledge-base`.
28
- 2. Read `.interf/stage-contract.json` and treat it as authoritative.
29
- 3. Read `.interf/summarize-targets.json` when present and treat `targets[]` as the source of truth for which files to summarize.
30
- If a target includes `output`, write the summary to that exact relative path.
31
- 4. Read any local docs listed by the stage contract.
32
- 5. Create one summary file in `summaries/` for each target source file.
33
- 6. Write `.interf/inventory.json`.
34
- 7. Emit `DONE:` and stop.
35
-
36
- If the CLI provided a summarize plan, do not re-audit the whole knowledge base before writing summaries.
37
-
38
- ## Status contract
39
-
40
- When launched by the Interf CLI:
41
- - emit exactly one startup line: `STATUS: loaded summarize plan N files`
42
- - emit `STATUS: batch committed` only after summary files and inventory were actually written
43
- - emit `DONE: summarize complete N/N` when the required writes are complete
44
- - do not emit per-file progress
45
-
46
- ## Execution bias
47
-
48
- This stage is a light per-file evidence pass, not a mini research project.
49
-
50
- - process only the files listed in `.interf/summarize-targets.json`
51
- - for a single large PDF, deck, or report, do one lightweight evidence pass and then stop
52
- - for a single large PDF, deck, or report, do at most one routing pass across the document plus one focused follow-up read that covers no more than 3 routed pages or sections
53
- - capture the file's scope, headline facts that are directly exposed, and whether important evidence also lives in charts or tables
54
- - if the document repeats the same template across many pages or entities, sample only enough pages to describe that repeated structure and preserve routing for later interfaces
55
- - do not chase every page, every market, every appendix, or every historical chart in this stage
56
- - leave narrow task-specific extraction to interface workflows
57
- - once you can state the document scope, the exposed headline metrics, and where deeper chart/table evidence lives, write the summary immediately
58
- - once the summary file and inventory are written, stop immediately
59
- - keep bulk PDF/OCR extraction output out of the run log. Save scratch output to temp files and inspect only the routed slices you need for the summary.
60
- - keep scratch extraction commands single-purpose and non-destructive. Do not use `rm`, wildcard cleanup, `;`, or `&&` chains during summarize.
61
- - if a shell pattern is blocked, do not retry the same chained command with minor edits. Switch to a simpler local read path and keep moving.
62
- - if you have already checked whether the summary file exists and it does not, the next step is to write it rather than doing another exploratory read
63
- - do not precreate `.interf/inventory.json` with `touch`; write the final JSON document directly
64
- - when updating `.interf/inventory.json`, rewrite the full JSON document in one whole-file write instead of appending or patching partial lines
65
- - do not use `apply_patch` or line-matched diffs on `.interf/inventory.json`; replace the file in one complete write
66
- - when you are ready to write, prefer a direct whole-file shell write such as `cat > path <<'EOF' ... EOF` for summary markdown and the inventory artifact
67
- - whole-file shell writes for stage artifacts are allowed and preferred here; do not stall deciding between patch-based editing and direct writes
68
-
69
- ## Summary output format
70
-
71
- Create one markdown file per source file under `summaries/`.
72
- Every summary filename must end in `.md`, even when the source file is `.txt`, `.pdf`, or another format.
73
- If the source file already ends in `.md`, keep a single `.md` suffix instead of appending another one.
74
- When `.interf/summarize-targets.json` provides `targets[].output`, use that exact path instead of inferring a filename.
75
-
76
- Each summary must include JSON frontmatter with:
77
- - `source`
78
- - `source_kind`
79
- - `evidence_tier`
80
- - `truth_mode`
81
- - `state`
82
- - `abstract`
83
-
84
- Use JSON frontmatter wrapped in `---` markers. Do not use YAML `key: value` frontmatter.
85
-
86
- Example:
87
-
88
- ```markdown
89
- ---
90
- {
91
- "source": "go-to-market-notes.txt",
92
- "source_kind": "note",
93
- "evidence_tier": "primary",
94
- "truth_mode": "proposed",
95
- "state": "draft",
96
- "abstract": "Short source-grounded description."
97
- }
98
- ---
99
- ```
100
-
101
- Each summary must include these sections:
102
- - `## Overview`
103
- - `## Key Takeaways`
104
-
105
- `## References` is optional.
106
-
107
- Keep summaries source-grounded:
108
- - do not overstate certainty
109
- - keep titles descriptive and conservative
110
- - preserve evidence tiers and truth modes
111
- - keep links sparse and obvious
112
- - for PDFs, decks, and reports, capture material table/chart/figure evidence when it affects the source's meaning
113
- - preserve the main headline metrics for the top-level sections or market groups when they are present in extractable text
114
- - preserve easy headline values from prose or clearly exposed tables when they are central to the source
115
- - for market reports and dashboards, preserve the main peer groups that are trivial to recover from prose or headline tables, but do not turn summarize into a full market-by-market extraction pass
116
- - if important evidence appears to live in charts or other visuals, say that clearly in the summary and preserve enough routing detail for a later interface or manual query step
117
- - do not turn the knowledge-base summarize stage into an exhaustive visual extraction pass across the whole report
118
- - if exact chart numbers are not directly recoverable from the same page with light local extraction, say so explicitly in the summary instead of flattening the evidence into vague prose
119
- - when useful, note whether important evidence came from prose, tables, or charts so later interface stages know when raw visual inspection may still be needed
120
- - distinguish `chart present and relevant` from `exact chart values not yet extracted`
121
-
122
- This is a per-file evidence stage only. Cross-file synthesis belongs to `knowledge-base/compile`.
123
-
124
- ## Inventory output
125
-
126
- Write `.interf/inventory.json` so every source file is accounted for.
127
-
128
- Minimum shape:
129
- - prefer the current runtime shape: top-level `entries` plus `total`
130
- - `total` equal to the actual current source-file count
131
- - one `entries[]` object per source file
132
- - each entry should preserve at least `source`, `summary`, and a conservative summarize `status` or `state`
133
- - per-file routing must let the runtime and validators see which raw file maps to which summary
134
-
135
- Do not copy canned totals or filenames into the runtime inventory.
136
- Do not invent new top-level inventory keys when `entries` already fits the run.
137
-
138
- The CLI reconciles `.interf/state.json` and refreshes `.interf/health.json` after stage validation.
139
- For a one-file summarize run, the finish sequence is strict: write the summary file, rewrite `.interf/inventory.json`, emit `STATUS: batch committed`, emit the standard summarize `DONE:` line using the current run counts, and stop.
140
-
141
- ## Guardrails
142
-
143
- - Do not modify source files.
144
- - Do not emit `STATUS: batch committed` before files exist on disk.
145
- - Do not create placeholder JSON files with `touch` before writing the final documents.
146
- - Do not append a second JSON object to `.interf/inventory.json`. Rewrite the whole file once.
147
- - Do not use `apply_patch` or line-matched diffs to edit `.interf/inventory.json`.
148
- - Use a single whole-file write for each required artifact as soon as the summary text is ready.
149
- - If you check whether a required summary or inventory artifact exists and it is missing, create it next instead of doing another exploratory read.
150
- - Do not keep mining the source after a usable conservative summary already exists.
151
- - Do not keep browsing after the required writes are complete.
152
- - If a required path is missing or unreadable, emit one `BLOCKED:` or `ERROR:` line with the concrete reason and stop.
@@ -1,159 +0,0 @@
1
- # Interf Interface
2
-
3
- Focused local context shells on top of your knowledge base. Any coding agent can navigate them.
4
-
5
- ## Architecture
6
-
7
- ```text
8
- source-folder/
9
- interf/
10
- {knowledge-base-name}/ knowledge base
11
- interfaces/
12
- {name}/ interface
13
- interf.json type: interface, workflow, knowledge_base.path
14
- compile-plan.md interface execution plan
15
- AGENTS.md bootstrap
16
- CLAUDE.md Claude Code bootstrap mirror
17
- workflow/ local workflow package
18
- home.md entry point
19
- .gitignore
20
- .interf/ hidden runtime state
21
- knowledge/ local entities/claims/indexes
22
- briefs/ hero documents
23
- summaries/ periodic summaries
24
- ```
25
-
26
- Interfaces are usually created by `interf create interface` from the source folder for a knowledge base. The source folder is the human control plane. The interface is the generated workspace for one job.
27
-
28
- Contract model:
29
- - `type` = engine object kind in config/schema (`interface`)
30
- - `workflow` = user-facing methodology selection
31
- - `.interf/stage-contract.json` = generated per-run contract for the active stage
32
- - executor = the agent/runtime that implements the active stage
33
-
34
- ## Compile flow
35
-
36
- ```text
37
- interf compile:
38
- Step 1/3: interface/retrieve scan all summary frontmatter, prove coverage, compute delta
39
- Step 2/3: interface/analyze batch analysis, extract, refine runtime from evidence
40
- Step 3/3: interface/compile create local context shell, validate
41
- ```
42
-
43
- State bridges between steps. If step 2 fails, the next run resumes from step 2.
44
-
45
- ## Workflows
46
-
47
- Shipped built-in interface workflow:
48
- - `interf`
49
-
50
- The selected workflow is written to `interf.json` and can seed starter local `workflow/` docs.
51
- Use `compile-plan.md` for interface-specific direction such as target entities, years, metrics, chart families, and output focus.
52
- Create a reusable local workflow only when you want a named method variation you expect to reuse across multiple interfaces.
53
-
54
- ## Bundled stage skills
55
-
56
- | Skill | Step | What |
57
- |---|---|---|
58
- | `interface/create` | — | Create interface, draft the initial runtime hypothesis |
59
- | `interface/retrieve` | 1/3 | Scan the full knowledge-base summary set, persist retrieval proof, compute delta |
60
- | `interface/analyze` | 2/3 | Batch analysis, subagents, extract entities/claims |
61
- | `interface/compile` | 3/3 | Build local outputs, validate, clean up |
62
-
63
- ## interf.json
64
-
65
- Minimal. Source of truth for type and knowledge-base reference.
66
-
67
- ```json
68
- {
69
- "type": "interface",
70
- "name": "weekly-briefing",
71
- "workflow": "interf",
72
- "knowledge_base": {
73
- "path": "../.."
74
- }
75
- }
76
- ```
77
-
78
- `knowledge_base.path` points to the parent knowledge base. All interface-specific filter criteria, extraction goals, and output specs live in `compile-plan.md`.
79
- `workflow` records the selected reusable method. Interf generates per-run stage contracts from it for this interface.
80
-
81
- If you want to specialize this specific interface, refine `compile-plan.md`.
82
- If you want a reusable retrieval, ontology, or output method, use a workflow and local `workflow/`.
83
- If you want a different stage graph, proof model, or required artifacts, that is effectively a new workflow.
84
-
85
- `AGENTS.md` is the source of truth. `CLAUDE.md` is a generated mirror so Claude Code picks up the same interface instructions automatically.
86
-
87
- `workflow/` is where you can edit interface-local instruction docs:
88
- - `workflow/README.md`
89
- - `workflow/create/SKILL.md`
90
- - `workflow/use/query/SKILL.md`
91
- - `workflow/compile/stages/retrieve/SKILL.md`
92
- - `workflow/compile/stages/analyze/SKILL.md`
93
- - `workflow/compile/stages/compile/SKILL.md`
94
-
95
- Simplest pattern:
96
- - edit `workflow/compile/stages/retrieve/SKILL.md` to change retrieval logic
97
- - edit `workflow/compile/stages/analyze/SKILL.md` to change ontology/extraction logic
98
- - edit `workflow/compile/stages/compile/SKILL.md` to change output/navigation logic
99
- - edit `workflow/use/query/SKILL.md` to change the manual interface query loop
100
-
101
- Workflow seeds may already place starter docs in these folders. Treat them as editable local guidance, not as locked system files.
102
- Use `AGENTS.md` for navigation, command usage, and the manual access checklist. Use `workflow/` for query behavior and stage behavior.
103
-
104
- These are the local instruction layer for the interface. Add JSON frontmatter with `mode: extend` or `mode: override` when you want to declare whether a doc should add to or replace the bundled stage instructions for that stage.
105
-
106
- Interf still enforces the same coverage proof, artifact schema, and state flow either way.
107
- If you need a different stage chain, artifact contract, or verifier flow, create a new workflow in the SDK instead of encoding that in local skill docs.
108
-
109
- If your coding agent is sandboxed to the current directory tree, launch it from the source folder so the source root, knowledge base, and this interface all stay reachable.
110
- Use `../../.interf/source-access.json` to verify that raw files are actually reachable before you depend on raw fallback in a manual agent session. `suggested_checks` are canonical absolute file paths so they remain valid from inside the interface folder.
111
-
112
- If Obsidian viewer defaults are enabled during `interf init`, newly created interfaces get minimal `.obsidian/graph.json` defaults. They are not registered as standalone workspaces by default; browse them from the parent knowledge-base workspace in Obsidian so knowledge-base summaries and source links remain navigable.
113
-
114
- ## Runtime files
115
-
116
- Interfaces maintain runtime artifacts under `.interf/`:
117
- - `state.json` — mutable runtime state
118
- - `health.json` — computed compile status and key metrics
119
- - `view-spec.json` — presentation contract for cards, graph scope, and navigation
120
- - `run.json` — current or last deterministic stage run
121
- - `stage-contract.json` — machine-readable contract for the active stage
122
- - `run-history.jsonl` — append-only history of completed runs
123
- - `relevant.json` — selected files for this interface
124
- - `coverage.json` — retrieval proof for this run
125
-
126
- `interf status` for an interface is read-only and deterministic. It checks config, knowledge-base path resolution, broken wikilinks, and retrieval coverage.
127
- `interf verify interface-plan --json` is the deterministic referee for the scaffold and `compile-plan.md`.
128
- `interf verify retrieve --json` is the deterministic referee for interface retrieval proof before analyze/build.
129
-
130
- See `docs/runtime-contract.md` for the human-readable contract and `src/lib/schema.ts` for the exact runtime schemas.
131
-
132
- ## compile-plan.md
133
-
134
- Generated by `interface/create`. Defines:
135
- - Stage 1: filter criteria
136
- - Stage 2: extraction goals and allowed runtime refinements
137
- - Stage 3: output specs for the local context shell
138
-
139
- This is the interface-specific customization layer for the built-in `interf` workflow unless you choose a reusable local workflow instead.
140
- Compile can refine it when the evidence clearly demands better local structure.
141
-
142
- ## Key principles
143
-
144
- **Local outputs only.** The parent knowledge base is read-only. The interface builds its own `knowledge/` and output folders.
145
-
146
- **No auto-cascade.** Knowledge-base compile and interface compile are separate commands.
147
-
148
- **Delta compile.** On subsequent runs, only changed files are processed.
149
-
150
- **Coverage-gated retrieval.** Retrieval is complete only when the system can prove the full summary set was scanned at the routing layer, candidate abstracts were reviewed, and selected plus rejected sets were persisted.
151
-
152
- **Local context shell.** The interface is not just a report folder. It should become the easiest place for an agent to enter, navigate, and understand the relevant slice of the knowledge base.
153
-
154
- ## Reset
155
-
156
- ```text
157
- interf reset compile remove knowledge/ + briefs/, keep summaries/ + config
158
- interf reset all remove all generated content, preserve config files
159
- ```
@@ -1,102 +0,0 @@
1
- # Interface Patterns
2
-
3
- Interf currently ships one built-in interface workflow: `interf`.
4
- That workflow always runs retrieve -> analyze -> compile.
5
-
6
- What changes from interface to interface is the use case, the `compile-plan.md` customization, and any optional local workflow extension docs.
7
-
8
- Use the patterns below as planning lenses you can encode in `compile-plan.md` or a reusable local interface workflow. They are not built-in workflow ids.
9
-
10
- Benchmark queries exist today as validation prompts and expected behaviors. The automated benchmark runner and score logging loop are implemented separately from this shipped template reference.
11
-
12
- ---
13
-
14
- ## Current-State Briefing Lens
15
-
16
- Current-state briefing. Best when you want the latest truth, recent changes, and immediate next steps.
17
-
18
- **Questions this interface answers:**
19
- - What is true right now?
20
- - What changed recently?
21
- - What should I focus on next?
22
- - Which decisions or risks are active?
23
-
24
- **Filter:** categories include current-state docs, changelogs, plans, updates, decisions
25
-
26
- **Outputs:**
27
- - Current-State.md — current truth with citations
28
- - Changes.md — recent changes and trend lines
29
- - Next-Steps.md — action-oriented follow-through
30
-
31
- **Summaries:** weekly, monthly, or milestone-based
32
-
33
- **Benchmark queries:**
34
- - "What is true right now?" — should prefer current, confirmed signals over stale material
35
- - "What changed recently?" — should compare recent vs prior, not show random old notes
36
- - "What should happen next?" — should surface evidence-linked actions, not generic advice
37
-
38
- ---
39
-
40
- ## Research Synthesis Lens
41
-
42
- Research synthesis. Best when you want themes, contradictions, evidence strength, and open questions from a dense knowledge base.
43
-
44
- **Questions this interface answers:**
45
- - What are the dominant themes?
46
- - Which claims are well-supported?
47
- - Where do sources disagree?
48
- - What questions still need more evidence?
49
-
50
- **Filter:** categories include primary sources, papers, notes, experiments, datasets, repos
51
-
52
- **Outputs:**
53
- - Themes.md — recurring themes with evidence
54
- - Contradictions.md — disagreements, caveats, counterevidence
55
- - Open-Questions.md — unresolved questions and next reads
56
-
57
- **Summaries:** by topic cluster or period
58
-
59
- **Benchmark queries:**
60
- - "What are the strongest themes?" — should show themes with citations, not loose impressions
61
- - "Where do sources disagree?" — should show both sides and the evidence basis
62
- - "What should I read next?" — should turn gaps into concrete next-source suggestions
63
-
64
- ---
65
-
66
- ## Gap Review Lens
67
-
68
- Audit and gap-finding. Best when you want to improve knowledge-base quality, spot stale areas, and surface missing or contradictory evidence.
69
-
70
- **Questions this interface answers:**
71
- - What is missing or weakly covered?
72
- - Which facts or claims look inconsistent?
73
- - Which outputs need verification or refresh?
74
- - What should be added to the knowledge base next?
75
-
76
- **Filter:** categories include canonical records, requirements, policies, status docs, recent changes
77
-
78
- **Outputs:**
79
- - Gaps.md — missing areas and thin coverage
80
- - Contradictions.md — inconsistent facts or claims
81
- - Follow-Ups.md — concrete verification or ingestion work
82
-
83
- **Benchmark queries:**
84
- - "What is missing?" — should identify concrete gaps, not generic advice
85
- - "What looks inconsistent?" — should cite the conflicting evidence explicitly
86
- - "What should we verify next?" — should turn issues into concrete follow-up work
87
-
88
- ---
89
-
90
- ## Self-improving Loop
91
-
92
- Every interface can carry benchmark queries. The intended validation cycle is:
93
-
94
- 1. Build the interface from its config and current compile plan
95
- 2. Run benchmark queries against the compiled interface workspace
96
- 3. Score: did each query return expected behavior?
97
- 4. If score is below threshold:
98
- - Analyze failures
99
- - Adjust the interface plan and ontology in `compile-plan.md`
100
- - Re-compile
101
- - Re-benchmark
102
- 5. Log scores per model per interface for comparison
@@ -1,137 +0,0 @@
1
- # Interf Knowledge Base
2
-
3
- Your local knowledge base for agents. Attach to any folder, then let Interf compile source files into summaries plus a cross-file knowledge layer.
4
-
5
- ## Architecture
6
-
7
- ```text
8
- source-folder/ user's files (untouched)
9
- └── interf/
10
- └── {knowledge-base-name}/ knowledge base
11
- ├── interf.json type: knowledge-base, workflow, name, source.path
12
- ├── AGENTS.md bootstrap
13
- ├── CLAUDE.md Claude Code bootstrap mirror
14
- ├── workflow/ local workflow package
15
- ├── home.md entry point
16
- ├── .interfignore source exclusion patterns
17
- ├── .gitignore
18
- ├── .interf/ hidden runtime state
19
- │ ├── state.json
20
- │ ├── health.json
21
- │ ├── source-access.json
22
- │ └── view-spec.json
23
- ├── summaries/ per-file evidence objects
24
- ├── knowledge/
25
- │ ├── entities/
26
- │ ├── claims/
27
- │ └── indexes/
28
- └── interfaces/
29
- └── {name}/ task-specific interfaces for specific jobs
30
- ```
31
-
32
- Knowledge bases are created by `interf create knowledge-base` from the source folder. The source folder is the human control plane. The knowledge base is the generated workspace. One source folder can host multiple named knowledge bases under `interf/` when you want to compare workflows over the same folder.
33
-
34
- Contract model:
35
- - `type` = engine object kind in config/schema (`knowledge-base`)
36
- - `workflow` = user-facing methodology selection
37
- - `.interf/stage-contract.json` = generated per-run contract for the active stage
38
- - executor = the agent/runtime that implements the active stage
39
-
40
- ## Processing flow
41
-
42
- ```text
43
- cd source-folder
44
- interf create knowledge-base → creates ./interf/<knowledge-base-name>/
45
- interf compile:
46
- Step 1/2: summarize source files into evidence objects → summaries/
47
- Step 2/2: compile cross-file knowledge + retrieval → knowledge/ + home.md
48
- ```
49
-
50
- ## Workflows
51
-
52
- Shipped knowledge-base workflows:
53
- - `interf`
54
- - `karpathy`
55
-
56
- Create new reusable workflows from the wizard when you want a named local variation.
57
-
58
- The selected workflow is written to `interf.json` and can seed starter local `workflow/` docs.
59
-
60
- ## Bundled stage skills
61
-
62
- | Skill | Step | What |
63
- |---|---|---|
64
- | `knowledge-base/summarize` | 1/2 | Generate source-grounded evidence objects for unprocessed source files |
65
- | `knowledge-base/compile` | 2/2 | Build the cross-file knowledge layer and retrieval structures |
66
-
67
- ## interf.json
68
-
69
- Minimal config. Points to the source folder:
70
-
71
- ```json
72
- {
73
- "type": "knowledge-base",
74
- "name": "my-notes",
75
- "workflow": "interf",
76
- "source": {
77
- "path": "../.."
78
- }
79
- }
80
- ```
81
-
82
- `workflow` records the selected methodology. Interf generates per-run stage contracts from it for this knowledge base.
83
-
84
- If you want different stage behavior or domain bias, use a workflow and local `workflow/`.
85
- If you want a different stage graph, proof model, or required artifacts, that is effectively a new workflow.
86
-
87
- `AGENTS.md` is the source of truth. `CLAUDE.md` is a generated mirror so Claude Code picks up the same knowledge-base instructions automatically.
88
-
89
- `workflow/` is where you can edit knowledge-base-local instruction docs:
90
- - `workflow/README.md`
91
- - `workflow/create/SKILL.md`
92
- - `workflow/use/query/SKILL.md`
93
- - `workflow/compile/stages/summarize/SKILL.md`
94
- - `workflow/compile/stages/compile/SKILL.md`
95
-
96
- Simplest pattern:
97
- - edit `workflow/compile/stages/summarize/SKILL.md` to change summarize logic
98
- - edit `workflow/compile/stages/compile/SKILL.md` to change knowledge-base compile logic
99
- - edit `workflow/use/query/SKILL.md` to change the manual query loop
100
-
101
- Workflow seeds may already place starter docs in these folders. Treat them as editable local guidance, not as locked system files.
102
- Use `AGENTS.md` for navigation, command usage, and the manual access checklist. Use `workflow/` for query behavior and stage behavior.
103
-
104
- These are the local instruction layer for the knowledge base. Add JSON frontmatter with `mode: extend` or `mode: override` when you want to declare whether a doc should add to or replace the bundled stage instructions for that stage.
105
-
106
- Interf still enforces the same proof contract, artifact schema, and state flow either way.
107
- If you need a different stage chain, artifact contract, or verifier flow, create a new workflow in the SDK instead of encoding that in local skill docs.
108
-
109
- If your coding agent is sandboxed to the current directory tree, launch it from the source folder so both raw files and this knowledge base stay reachable.
110
- Use `.interf/source-access.json` to verify that raw files are actually reachable before you depend on raw fallback in a manual agent session. `suggested_checks` are canonical absolute file paths so they still work from nested interface folders.
111
-
112
- ## Status
113
-
114
- Knowledge bases maintain runtime artifacts under `.interf/`:
115
- - `state.json` — mutable runtime state
116
- - `health.json` — computed trust surface for summarize/compile status
117
- - `source-access.json` — raw-file access quick check for manual sessions
118
- - `run.json` — current or last deterministic stage run
119
- - `stage-contract.json` — machine-readable contract for the active stage
120
- - `run-history.jsonl` — append-only history of completed runs
121
- - `view-spec.json` — viewer-neutral layout contract
122
-
123
- `interf status` is read-only and deterministic. It runs source discovery, checks config, summary frontmatter, abstract minimums, and broken wikilinks.
124
- Use `interf verify summarize --json` after summary generation and `interf verify compile --json` after knowledge-base compilation for explicit pass/fail checks when testing the workflow or driving it from an agent.
125
-
126
- See `docs/runtime-contract.md` for the human-readable contract and `src/lib/schema.ts` for the exact runtime schemas.
127
-
128
- ## Scan accountability
129
-
130
- `knowledge-base/compile` writes an inventory of all `summaries/` files before scanning. The scanned count must equal the inventory count. If it does not, the skill stops and reports the gap.
131
-
132
- ## Reset
133
-
134
- ```text
135
- interf reset compile remove knowledge/, keep summaries/
136
- interf reset all remove all generated content, preserve source files
137
- ```
@@ -1,19 +0,0 @@
1
- # Files and directories to exclude from interf source discovery.
2
- # Same syntax as .gitignore.
3
-
4
- # Build artifacts
5
- dist/
6
- build/
7
- out/
8
-
9
- # Logs and temp files
10
- *.log
11
- *.tmp
12
-
13
- # Environment and secrets
14
- .env
15
- .env.*
16
-
17
- # OS files
18
- .DS_Store
19
- Thumbs.db