@noir-ai/create 1.13.0 → 1.14.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noir-ai/create",
-  "version": "1.13.0",
+  "version": "1.14.0-beta.1",
   "description": "Noir scaffold engine — the idempotent declarative writer, manifest, templates, stack-detect, and migrations that power `noir init`/`create`/`sync`.",
   "license": "MIT",
   "author": "agaaaptr",
@@ -46,8 +46,8 @@
     "templates"
   ],
   "dependencies": {
-    "@noir-ai/core": "1.13.0",
-    "@noir-ai/adapters": "1.13.0"
+    "@noir-ai/adapters": "1.14.0-beta.1",
+    "@noir-ai/core": "1.14.0-beta.1"
   },
   "devDependencies": {
     "@types/node": "^22.17.0"

package/templates/config.env.tmpl

@@ -0,0 +1,75 @@
+# .noir/.env — project-scoped configuration for this repo.
+#
+# This file is the recommended home for project-scoped configuration and
+# secrets. Precedence:
+#   1. run profile env     run.profiles.<n>.env      (per-invocation; merges OVER)
+#   2. .noir/.env          <- recommended home for project-scoped configuration
+#   3. real environment    CI / container / launchd / shell rc
+#   4. built-in default
+#
+# A real environment variable is a FALLBACK: it applies only to keys this file
+# leaves unset. A machine-global export therefore cannot shadow a value here.
+# Run `noir env` to see which source is winning for each key.
+#
+# Keep this file private: chmod 600 .noir/.env
+# It is gitignored by Noir's managed .gitignore block, and Noir REFUSES to load
+# it if it is tracked by git (a cloned repo could redirect credentials).
+# Never commit it.
+#
+# EVERY LINE BELOW IS COMMENTED OUT. `noir init` created this file at mode 0600
+# with no active value, so it parses to an empty overlay and changes no
+# behaviour. Uncomment only what you enable, and fill in a real value.
+# `.noir/.env.example` carries the same set and stays committable.
+#
+# Full reference: docs/reference/environment.md
+
+# --- Integrations -----------------------------------------------------------
+# ClickUp — only if the noir-clickup integration is enabled.
+# CLICKUP_API_TOKEN=pk_00000000000000000000000000000000
+#
+# CLICKUP_TEAM_ID is NOT an env var — Noir never reads it. Workspace binding
+# (team/list/space ids) is config.yml instead:
+#   integrations:
+#     clickup:
+#       teamId: "ABC123"   # optional — only for custom task IDs (#ABC-123)
+
+# --- Remote embedders (context.embedder.kind: remote) -----------------------
+# The default local embedder (kind: local) needs no key.
+# OPENAI_API_KEY=sk-000000000000000000000000000000000000000000000000
+# VOYAGE_API_KEY=pa-0000000000000000000000000000000000000000000000
+# COHERE_API_KEY=0000000000000000000000000000000000000000
+#
+# Ollama (kind: ollama) reads its base URL from config.yml
+# (context.embedder.baseURL); this variable is the fallback:
+# OLLAMA_BASE_URL=http://localhost:11434
+
+# --- Model provider key -----------------------------------------------------
+# There is NO fixed "model key" variable, and setting one is not enough on its
+# own. `apiKeyEnv` is a NAME, not an interpolation: the config stores the
+# variable NAME and Noir reads process.env[<that name>] at call time. Write the
+# bare name — never `${...}` — in .noir/config.yml:
+#
+#   model:
+#     providers:
+#       anthropic:
+#         apiKeyEnv: ANTHROPIC_API_KEY   # -> reads $ANTHROPIC_API_KEY
+#     tiers:
+#       default:
+#         provider: anthropic
+#
+# Only `run.profiles.<name>.env` interpolates `${VAR}`. With no provider
+# configured the model layer degrades to templates — Noir never makes a silent
+# paid call. `ANTHROPIC_API_KEY` is the conventional example, not a variable
+# Noir looks up on its own:
+# ANTHROPIC_API_KEY=sk-ant-0000000000000000000000000000000000000000000000
+
+# --- Run profile selection --------------------------------------------------
+# Selects a `run.profiles.<name>` entry for `noir run`.
+# Precedence: --profile flag > NOIR_PROFILE > run.defaultProfile > host default.
+# NOIR_PROFILE=work
+
+# --- Update kill-switches ---------------------------------------------------
+# NOIR_DISABLE_UPDATE_CHECK=1   # suppress the background startup check only
+# NOIR_DISABLE_UPDATES=1        # make `noir update` refuse (exit 2)
+
+# See docs/reference/environment.md for every variable Noir reads.

package/templates/config.yml.tmpl

@@ -1,2 +1,8 @@
 host: {{host}}
 mode: full
+
+# noir:env-pointer
+# This file is safe to commit: it holds no secrets.
+# Project-scoped values and secrets belong in .noir/.env (gitignored, mode
+# 0600). .noir/.env.example documents the full variable set; `noir env`
+# reports which source wins for each key.

package/templates/env.example.tmpl

@@ -1,11 +1,79 @@
-# .noir/.env.example — copy to `.noir/.env` and fill in real values.
-# `.noir/.env` is gitignored — NEVER commit real tokens. Real environment
-# variables always win over this file (it fills only unset keys).
+# .noir/.env.example — committable documentation of the format.
 #
-# noir-clickup integration (only if you use the noir-clickup skill):
+# This file is a TEMPLATE and is never loaded. Noir reads `.noir/.env`, which
+# `noir init` already created for you at mode 0600 — edit that file and
+# uncomment the entries you need. Keep this example in git so the variable set
+# stays discoverable.
+#
+# ---------------------------------------------------------------------------
+# The block below is the same header `.noir/.env` carries (spec 12.1).
+# ---------------------------------------------------------------------------
+#
+# .noir/.env — project-scoped configuration for this repo.
+#
+# This file is the recommended home for project-scoped configuration and
+# secrets. Precedence:
+#   1. run profile env     run.profiles.<n>.env      (per-invocation; merges OVER)
+#   2. .noir/.env          <- recommended home for project-scoped configuration
+#   3. real environment    CI / container / launchd / shell rc
+#   4. built-in default
+#
+# A real environment variable is a FALLBACK: it applies only to keys this file
+# leaves unset. A machine-global export therefore cannot shadow a value here.
+# Run `noir env` to see which source is winning for each key.
+#
+# Keep this file private: chmod 600 .noir/.env
+# It is gitignored by Noir's managed .gitignore block, and Noir REFUSES to load
+# it if it is tracked by git (a cloned repo could redirect credentials).
+# Never commit `.noir/.env`. (THIS file is the committable one.)
+
+# --- Integrations -----------------------------------------------------------
+# ClickUp — only if the noir-clickup integration is enabled.
 # CLICKUP_API_TOKEN=pk_00000000000000000000000000000000
 #
-# CLICKUP_TEAM_ID is NOT an env var — set it as a config.yml key instead:
+# CLICKUP_TEAM_ID is NOT an env var — Noir never reads it. Workspace binding
+# (team/list/space ids) is config.yml instead:
 #   integrations:
 #     clickup:
 #       teamId: "ABC123"   # optional — only for custom task IDs (#ABC-123)
+
+# --- Remote embedders (context.embedder.kind: remote) -----------------------
+# The default local embedder (kind: local) needs no key.
+# OPENAI_API_KEY=sk-000000000000000000000000000000000000000000000000
+# VOYAGE_API_KEY=pa-0000000000000000000000000000000000000000000000
+# COHERE_API_KEY=0000000000000000000000000000000000000000
+#
+# Ollama (kind: ollama) reads its base URL from config.yml
+# (context.embedder.baseURL); this variable is the fallback:
+# OLLAMA_BASE_URL=http://localhost:11434
+
+# --- Model provider key -----------------------------------------------------
+# There is NO fixed "model key" variable, and setting one is not enough on its
+# own. `apiKeyEnv` is a NAME, not an interpolation: the config stores the
+# variable NAME and Noir reads process.env[<that name>] at call time. Write the
+# bare name — never `${...}` — in .noir/config.yml:
+#
+#   model:
+#     providers:
+#       anthropic:
+#         apiKeyEnv: ANTHROPIC_API_KEY   # -> reads $ANTHROPIC_API_KEY
+#     tiers:
+#       default:
+#         provider: anthropic
+#
+# Only `run.profiles.<name>.env` interpolates `${VAR}`. With no provider
+# configured the model layer degrades to templates — Noir never makes a silent
+# paid call. `ANTHROPIC_API_KEY` is the conventional example, not a variable
+# Noir looks up on its own:
+# ANTHROPIC_API_KEY=sk-ant-0000000000000000000000000000000000000000000000
+
+# --- Run profile selection --------------------------------------------------
+# Selects a `run.profiles.<name>` entry for `noir run`.
+# Precedence: --profile flag > NOIR_PROFILE > run.defaultProfile > host default.
+# NOIR_PROFILE=work
+
+# --- Update kill-switches ---------------------------------------------------
+# NOIR_DISABLE_UPDATE_CHECK=1   # suppress the background startup check only
+# NOIR_DISABLE_UPDATES=1        # make `noir update` refuse (exit 2)
+
+# See docs/reference/environment.md for every variable Noir reads.

package/templates/gitignore.tmpl

@@ -1,8 +1,5 @@
 /.noir/store/
 /.noir/handoff/
-/.noir/*.sock
-/.noir/daemon.pid
-/.noir/state/
 /.noir/.env
 /.noir/.env.*
 !/.noir/.env.example

package/templates/noir-readme.md.tmpl

@@ -0,0 +1,57 @@
+# `.noir/` — the Noir project store
+
+This directory is the canonical project state — not the host's own files.
+Everything here is either emitted by `noir init` / `noir sync` or written by
+the feature named beside it.
+
+## What exists now
+
+| Path | What it is |
+| --- | --- |
+| `project.id` | Canonical project id. It names the store database (`store/<project.id>.db`) — don't regenerate it by hand. |
+| `config.yml` | Your config seed: host, mode, integrations, context / memory / model settings. Yours to edit. |
+| `NOIR.md` | The context brief the host context file `@`-imports. Noir-managed region. |
+| `rules/RULES.md` | The AI working contract the host `@`-imports. Yours to edit. |
+| `.env` | Project-scoped configuration and secrets (mode 0600, gitignored). |
+| `.env.example` | Committable documentation of the same variable set. Never loaded. |
+| `scaffold-version` | Which scaffold version produced this tree — drives `noir init --upgrade`. |
+| `ancestors.json` | Merge base for Noir's managed regions (leave it alone). |
+| `README.md` | This map. |
+
+Host-side pointers sit at the repository root, not here: `CLAUDE.md` (claude),
+`AGENTS.md` (agents-md / cursor / opencode) or `GEMINI.md` (gemini), plus that
+host's MCP config (`.mcp.json`, `.gemini/mcp.json`, `.cursor/mcp.json`,
+`opencode.json`). With `--host claude`, `router.md` and `hooks/` (the
+SessionStart contract and its runner) live here too.
+
+## What appears later
+
+Nothing below is created eagerly — each directory shows up the first time the
+feature that owns it runs, so an empty project stays empty. `store/`, `handoff/`
+and `transcripts/` hold runtime data and are gitignored; everything else is
+committed.
+
+| Directory | Written by | Triggered by |
+| --- | --- | --- |
+| `store/` | The daemon — single-writer SQLite + FTS5 + vectors | the first command that touches the store (`store/<project.id>.db`) |
+| `intake/`, `specs/`, `plans/`, `tasks/`, `clarifications/` | The SDD workflow phases | `noir task new` → `noir task advance` |
+| `decisions/` | The ADR stub written in the document phase | a task landing at `done` |
+| `audit/` | Task gate results, plus integration call logs | `noir task verify`, and the first integration call |
+| `transcripts/` | Raw host output (best effort) | `noir run <prompt>` |
+| `handoff/` | Session handoff prompts | `noir handoff --write` |
+
+## Where to go next
+
+- **Configuration** — `.noir/config.yml` holds host, mode, integrations and the
+  context / memory / model settings. `noir doctor` reports what is drifted and
+  what a re-emit would change.
+- **Environment variables** — put project-scoped values (and secrets) in
+  `.noir/.env`; `.noir/.env.example` documents the full set and is the file to
+  commit. The file **wins for every key it defines** — a real environment
+  variable is only the fallback for keys it leaves unset. There is no
+  `VAR=value noir ...` prefix level; for a genuine per-invocation value add a
+  `run.profiles.<name>.env` entry and select it with `noir run --profile <name>`.
+  `noir env` shows which source wins per key.
+- **The workflow** — `noir task new` starts the spec → plan → implement →
+  verify → document lifecycle, `noir status` shows where every task stands, and
+  `noir skills list` lists the on-demand skills your host can load.