1 · Install
Add the core package
npm install @cog/corePackage: @cog/core. The release package exposes the core language and installed command surface.
cog Developer Preview
Learn cog by running it.
cog is a small language and runtime for making cognitive operations explicit, composable, inspectable, and governable. This hub is the shortest path from installation to a working .cog program, then from primitives to reusable domain workflows.
Quick start
From zero to one runnable cognitive program
The Developer Preview targets Node 20 and npm 10 or newer. Use npxfor the first run so no global CLI installation is required.
2 · Inspect
See what your installation can do
npx cog help
npx cog discover
npx cog workflowsDiscovery matters because libraries and workflow capabilities should be read from the installed release rather than assumed from documentation.
3 · Write
Create observation.cog
Start with one explicit observation and one emission. The point is not the ambient-light example; it is learning the shape of a cognitive object that can be validated and executed.
define entity "observed-signal" {
kind: observation
level: L1
operation: observe
attribute: "ambient-light"
value: "present"
confidence: 1
}
emit {
target: "observed-signal"
kind: observation
}4 · Validate, then run
npx cog validate observation.cog
npx cog run observation.cogKeep validation before execution as the default habit. A cognitive program should fail visibly when its structure or semantics are not valid.
What ships
A language toolchain, not only a runtime library
The Developer Preview is intended to let a downstream developer install cog, inspect it, validate programs, run them, and learn from canonical examples without first writing a TypeScript harness.
Parser
Turns .cog source into the structured representation used by the compiler and validation pipeline.
Compiler
Compiles validated cognitive declarations and relations into the executable intermediate form used by the runtime.
Linter / validator
Surfaces structural and semantic problems before execution so invalid cognitive programs fail visibly.
Planner + runtime
Plans and executes governed cognitive workflows while preserving explicit operations, relations, constraints, and emissions.
CLI
Runs, validates, discovers libraries, and exposes workflow information without requiring a TypeScript harness.
Standard Library
Provides reusable domain libraries for common cognitive work instead of forcing every program to rebuild the same reasoning patterns.
CLI reference
Five commands to know first
| Command | Purpose |
|---|---|
| cog help | Show the installed command surface. |
| cog validate <file> | Parse and validate a .cog program without executing it. |
| cog run <file> | Execute a validated .cog program. |
| cog discover | List available domain libraries. |
| cog workflows | Inspect the workflow surface available to the installed release. |
Beginner's guide
Three levels of learning
Do not begin with the largest domain workflow. Learn the grammar of cognitive operations, learn to compose them, then use the standard library.
Level 1
Learn the cognitive primitives
Begin with the language elements that make cognition explicit: observation, identification, relation, classification, comparison, constraint, transformation, resolution, projection, and emission.
Outcome: You should be able to read a small .cog file and explain what cognitive operation each statement represents.
Level 2
Think in Unix-like cognitive commands
Use familiar command-line ideas as teaching analogies: inspect, filter, relate, transform, validate, and emit. The goal is compositional thinking, not pretending that every Unix command is a literal cog CLI command.
Outcome: You should be able to decompose a cognitive task into small operations that can be composed and inspected.
Level 3
Build complete cognitive workflows
Move from primitives into domain libraries and end-to-end applications such as research synthesis, editorial review, decision analysis, audit reasoning, and knowledge-graph work.
Outcome: You should be able to choose a library, adapt an example, validate it, and run a bounded cognitive workflow.
Examples
Read small programs before large ones
The repository groups canonical examples into primitives, pipelines, graphs, adapters, and applications. Start with primitives; use application examples when you are ready to see several operations composed into a domain workflow.
Primitive set
Canonical language primitives
Observation, identification, relation, classification, comparison, constraint, transformation, resolution, projection, and emission each have small canonical examples in the repository.
Open primitive examplesResearch synthesis
Observe sources, extract claims, compare them, cluster them, resolve the synthesis, and emit a final result.
Read the canonical example →Editorial review
Use a bounded workflow for document review, drift detection, reconciliation, and explanation.
Read the canonical example →Decision analysis
Represent alternatives, constraints, evaluation, and resolution as an inspectable cognitive workflow.
Read the canonical example →Audit reasoning
Model findings, relations, severity, and audit resolution without hiding the reasoning structure inside prose.
Read the canonical example →Knowledge graph
Identify nodes and profiles, relate them, form clusters, and emit explanatory correlation structures.
Read the canonical example →Standard Library
Discover reusable cognitive domains
Run cog discover against the installed release for the authoritative list. The Developer Preview library family is organized around reusable domains rather than one giant general-purpose workflow.
Research Synthesis
cog:domain:research
Editorial Review
cog:domain:editorial
Decision Analysis
cog:domain:decision
Audit Reasoning
cog:domain:audit
Knowledge Graph
cog:domain:graph
Human Orientation
cog:domain:orientation
Cognitive Ecology
cog:domain:cognitive-ecology
Devotional Intelligence
cog:domain:devotional-intelligence
Reference
Use the right source for the right question
WinMedia cog framework — what cog means and why its cognitive structure matters.
GitHub source — implementation, examples, tests, issues, and release code.
@cog/core on npm — the package destination for the Developer Preview.
Developer Preview boundary
Expect a real toolchain, not a finished platform
- The Developer Preview is for learning, experimentation, and bounded downstream use.
- Syntax, library shape, diagnostics, and runtime contracts may still change before a stable release.
- cog is not a hosted AI service, browser IDE, or replacement for the model or tools a workflow may call.
- Prefer small validated programs over large speculative architectures while learning the language.