@c4a/context 0.6.0-beta.8 → 0.6.1

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 (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +94 -54
  3. package/package.json +14 -1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 context4ai
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,32 +1,23 @@
1
- # @c4a/context
1
+ # Context SDK
2
2
 
3
- `@c4a/context` is the project-local SDK for Context workspaces.
3
+ [简体中文](./README.zh-CN.md)
4
4
 
5
- It provides the typed public surface used by `src/index.ts`: source references,
6
- phase declarations, review declarations, package declarations, and template
7
- metadata. `@c4a/context-cli` performs the filesystem side effects.
5
+ `@c4a/context` is the declarative SDK for a Context workspace. It provides the
6
+ typed API used by `src/index.ts` to describe sources, processing phases, review
7
+ gates, and package outputs. It does not perform filesystem writes or run the
8
+ workflow; those operations belong to the
9
+ [Context CLI](../context-cli/README.md).
8
10
 
9
- ## Install
11
+ ## Project Model
10
12
 
11
- Published users install through the workspace created by `context init`.
12
-
13
- For local SDK development:
14
-
15
- ```bash
16
- ./start.sh link
17
- context init context --dev
18
- cd context
19
- bun install
20
- ```
21
-
22
- ## Tiny Example
13
+ A Context project follows a sources-to-phases-to-packages model:
23
14
 
24
15
  ```ts
25
16
  import {
26
17
  defineProject,
27
18
  extractTs,
28
- reviewValidity,
29
19
  kbPackage,
20
+ reviewValidity,
30
21
  source,
31
22
  } from "@c4a/context";
32
23
 
@@ -51,50 +42,99 @@ export default defineProject({
51
42
  });
52
43
  ```
53
44
 
54
- ## Read Next
45
+ `src/index.ts` is similar to a Webpack configuration for knowledge. It defines
46
+ what enters the project, which transformations and gates run, and what is built
47
+ at the end. The installed Agent plugin includes the skills and SDK manuals
48
+ needed to maintain this configuration from a user's requirements.
49
+
50
+ ## Public Surface
51
+
52
+ | API | Purpose |
53
+ |---|---|
54
+ | `defineProject()` | Declares the complete project graph. |
55
+ | `source()` and `allSources()` | References registered repo, file, or Lark source boundaries. |
56
+ | `extractTs()` | Extracts TypeScript/TSX symbols and relationships into `codegraph` candidates. |
57
+ | `alignProse()` and `compileProse()` | Structures document evidence and compiles source-bound knowledge candidates. |
58
+ | `reviewValidity()` | Declares the review gate for one collection or the project. |
59
+ | `customPhase()` | Adds project-specific orchestration when built-in phase factories are not enough. |
60
+ | `kbPackage()` | Builds an Agent knowledge-base package from approved knowledge and templates. |
61
+ | `llmsPackage()` | Builds a single text bundle for model context or RAG import. |
62
+
63
+ Use the built-in phase factories first. `customPhase()` is an escape hatch for
64
+ project-specific orchestration, not a replacement for source, extraction,
65
+ review, and package lifecycle rules.
66
+
67
+ ## Knowledge Collections
68
+
69
+ Approved Markdown is organized under `knowledge/<collection>/`:
70
+
71
+ | Collection | What it contains | Typical sources |
72
+ |---|---|---|
73
+ | `codegraph` | Code symbols, modules, and relationships | Code repositories |
74
+ | `business` | Business concepts, roles, and relationships | Business and Lark documents |
75
+ | `product` | Product capabilities and behavior | Product and requirement documents |
76
+ | `architecture` | System structure and design explanations | Architecture and design documents |
77
+ | `sop` | Procedures, runbooks, and operational steps | Handbooks and operation documents |
78
+ | `faq` | Common questions and troubleshooting | FAQs, support documents, experience notes |
79
+ | `decision` | Decisions, alternatives, and trade-offs | Design reviews and decision records |
80
+ | `incident` | Incident timelines, response, and follow-up | Incident reports and retrospectives |
81
+ | `standards` | Normative rules and constraints | Engineering standards and business rules |
82
+ | `test` | Validation rules, scenarios, and acceptance criteria | Test plans and acceptance documents |
83
+ | `feats` | Capability records for a specific use case | Custom project workflows and approved knowledge |
84
+
85
+ Collections are semantic classifications, not final package directories.
86
+ Package build maps selected collections into OKF roots such as `wikis/`,
87
+ `guides/`, `rules/`, and `feats/`. One source may contribute to several
88
+ collections; classification should be based on evidence and user confirmation,
89
+ not filenames.
90
+
91
+ ## Package Templates
92
+
93
+ Package declarations point at editable templates under
94
+ `src/package-templates/`. Installed examples are available at:
55
95
 
56
- These files ship inside the installed package at `node_modules/@c4a/context/`:
57
-
58
- - [Docs index](./docs/README.md)
59
- - [Getting Started](./docs/getting-started.md)
60
- - [Agent Guide](./docs/guides/agent-guide.md)
61
- - [Package Outputs](./docs/guides/package-outputs.md)
62
- - [Project API](./docs/reference/project-api.md)
63
- - [Package Templates](./docs/reference/package-templates.md)
96
+ ```text
97
+ node_modules/@c4a/context/templates/package-templates/
98
+ ```
64
99
 
65
- Template examples ship in:
100
+ The default KB template includes:
66
101
 
67
102
  ```text
68
- node_modules/@c4a/context/templates/package-templates/
103
+ kb/
104
+ |-- AGENTS.md
105
+ |-- skills/
106
+ | `-- knowledge-query/SKILL.md
107
+ `-- wikis/index.md
69
108
  ```
70
109
 
71
- Copy them into a workspace under `src/package-templates/` when declaring
72
- `kbPackage()` or `llmsPackage()`.
110
+ The `knowledge-query` Skill teaches consuming Agents how to navigate indexes,
111
+ inspect approved knowledge, and cite evidence. A project can add more Skills or
112
+ template files under `wikis/`, `guides/`, `rules/`, and other package paths.
73
113
 
74
- Approved Markdown lives under internal `knowledge/<collection>/...` paths such
75
- as `knowledge/codegraph/...` or `knowledge/architecture/...`. During build, the
76
- CLI maps selected internal collections to OKF output roots such as `wikis/`,
77
- `guides/`, `rules/`, or `feats/`. OKF fields and Context extension fields live
78
- at the top level. Do not nest `sources`, `visibility`, or `code_symbols` under
79
- `context`, and do not add frontmatter `source_refs`. Section provenance lives in
80
- `context:section` source-ref comments.
114
+ Templates use Handlebars variables in file contents and paths. Common variables
115
+ include `{{packageName}}`, `{{displayName}}`, `{{knowledgeCount}}`,
116
+ `{{knowledgeGroups}}`, `{{knowledgeItems}}`, `{{knowledgeTree}}`, and
117
+ `{{buildInventory}}`.
81
118
 
82
- ## Boundary
119
+ For advanced routing and retrieval, a template may carry a local script such as
120
+ `query.ts`, with a Skill describing when and how an Agent should call it. The
121
+ Skill can also route the Agent to MCP servers, CLI commands, or other tools to
122
+ form a package-specific Agentic Search workflow.
83
123
 
84
- The SDK stays declarative:
124
+ ## State Boundary
85
125
 
86
- - `defineProject`
87
- - `source`, `allSources`
88
- - `extractTs`, `reviewValidity`, `customPhase`
89
- - `kbPackage`, `llmsPackage`
90
- - source registry reading and validation helpers
126
+ The SDK stays declarative. It may describe reads, writes, phases, review, and
127
+ package selection, but the CLI owns source materialization, capture, extraction,
128
+ review application, approved Markdown materialization, verification, and build.
129
+ Do not replace CLI lifecycle operations with direct edits to `sources/`,
130
+ `unapproved/`, `knowledge/`, or `dist/`.
91
131
 
92
- The CLI owns:
132
+ ## Documentation
93
133
 
94
- - source materialization
95
- - extraction
96
- - review HTML and review apply
97
- - approved Markdown materialization
98
- - package build
99
- - verification
100
- - status and next-step guidance
134
+ - [Documentation index](./docs/README.md)
135
+ - [Getting Started](./docs/getting-started.md)
136
+ - [Agent Guide](./docs/guides/agent-guide.md)
137
+ - [Project API](./docs/reference/project-api.md)
138
+ - [Package Outputs](./docs/guides/package-outputs.md)
139
+ - [Package Templates](./docs/reference/package-templates.md)
140
+ - [Template Variables](./docs/reference/template-variables.md)
package/package.json CHANGED
@@ -1,7 +1,20 @@
1
1
  {
2
2
  "name": "@c4a/context",
3
- "version": "0.6.0-beta.8",
3
+ "version": "0.6.1",
4
4
  "type": "module",
5
+ "description": "Context SDK — project-local configuration and workspace primitives",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/context4ai/context.git",
10
+ "directory": "packages/context"
11
+ },
12
+ "keywords": [
13
+ "context",
14
+ "sdk",
15
+ "knowledge",
16
+ "workspace"
17
+ ],
5
18
  "dependencies": {
6
19
  "yaml": "^2.5.1",
7
20
  "zod": "^3.23.8"