@aacombarro89/praxis 0.1.0

package/packages/layer1/instruction-upkeep/package.yaml

@@ -0,0 +1,8 @@
+# Package manifest (docs/wiki/packages-and-emit.md, D20). This package provides a standing
+# reminder (rules.md) plus the /praxis-audit command (commands/audit.md) that
+# keeps the authored instruction layer (CLAUDE.md, .claude/rules) current —
+# never the tool's native auto-memory, never a 3rd-party memory system
+# (docs/wiki/onboarding.md).
+name: instruction-upkeep
+layer: layer1
+provides: [rules, commands]

package/packages/layer1/instruction-upkeep/rules.md

@@ -0,0 +1,21 @@
+## Instruction upkeep
+
+The authored instruction layer (`CLAUDE.md`, `.claude/rules`) drifts as a
+project changes, and can be incomplete from the start. Keep it both current
+and complete:
+
+- When the project changes in a way that makes an instruction stale, or a
+  misunderstanding surfaces that's worth encoding, update the instruction
+  files rather than letting the gap persist.
+- An instruction file should document, for any project: build/test/run
+  commands, project layout, key conventions, and always-do rules. If one of
+  these is missing, fill it by discovery and asking the user — never invent
+  a fact that isn't backed by the code, config, or the user's answer.
+- Prefer linking a canonical source (e.g. an architecture doc) over restating
+  its facts — restated facts drift independently of their source.
+- When instruction files include `praxisAnchors` frontmatter, keep those anchors
+  resolving. `praxis check` hard-fails broken `path`, `command`, and `section`
+  anchors; staleness signals are future advisory work.
+- Make instruction-layer changes through `/praxis-audit`, not ad-hoc edits — run
+  it when unsure whether the instruction files still match the project, or whether
+  they cover the sections above.

package/packages/layer1/karpathy-claude/package.yaml

@@ -0,0 +1,5 @@
+# Package manifest (docs/wiki/packages-and-emit.md, D20). Declares what this package is and
+# provides; the loader (src/packages.ts) validates it and resolves requires/conflicts.
+name: karpathy-claude
+layer: layer1
+provides: [rules]

package/packages/layer1/karpathy-claude/rules.md

@@ -0,0 +1,35 @@
+## Methodology — Layer 1 (general)
+
+Behavioral guidelines that reduce common LLM coding mistakes. They are
+tool-agnostic; merge with project-specific instructions as needed.
+
+Tradeoff: these bias toward caution over speed. For trivial tasks, use judgment.
+
+### 1. Think before coding
+
+Don't assume, don't hide confusion, surface tradeoffs. State assumptions
+explicitly and ask when uncertain. Offer a simpler approach if one exists. Stop
+and ask when something is unclear rather than guessing.
+
+### 2. Simplicity first
+
+Write the minimum code that solves the problem. No speculative features, no
+abstractions for single-use code, no error handling for impossible cases. If 200
+lines could be 50, rewrite. Test: would a senior engineer call this
+overcomplicated?
+
+### 3. Surgical changes
+
+Touch only what the task requires. Don't refactor, reformat, or "improve"
+adjacent code. Match the existing style. Mention unrelated dead code rather than
+deleting it. Remove only the orphans your own change creates. Every changed line
+should trace to the request.
+
+### 4. Goal-driven execution
+
+Define success criteria, then loop until verified. "Add validation" becomes
+"write tests for invalid inputs, then make them pass." State a brief plan with a
+verify step per item.
+
+Working if: fewer unnecessary diffs, fewer rewrites from overcomplication, and
+clarifying questions before implementation rather than mistakes after.

package/packages/layer1/safe-permissions/package.yaml

@@ -0,0 +1,5 @@
+# Package manifest (docs/wiki/packages-and-emit.md, D20). This package provides a structured
+# permission policy (permissions.yaml), not prose — see docs/wiki/emitters.md/D18/D19.
+name: safe-permissions
+layer: layer1
+provides: [permissions]

package/packages/layer1/safe-permissions/permissions.yaml

@@ -0,0 +1,26 @@
+# Neutral permission policy — the enforcement side of the rails
+# (docs/wiki/emitters.md, D18/D19). Tool-agnostic INTENT expressed as capabilities; per-tool emitters
+# translate to concrete rule strings (Claude Code today; tools without a
+# permission model emit nothing). Edit your own settings to tune — Praxis owns
+# only the rules it emits and never clobbers rules you add.
+#
+# Posture: allow common local dev (smooth); prompt before anything that leaves the
+# machine or mutates dependencies; deny destructive / exfiltration actions.
+# Capability vocabulary is closed — see src/permissions.ts.
+
+allow:
+  - read-repo # read repository files
+  - edit-repo # create / edit / write repository files
+  - run-dev-scripts # test, lint, typecheck, build
+  - read-only-git # git status / diff / log
+  - git-commit # commit locally
+
+ask:
+  - git-push # pushes leave the machine
+  - install-deps # mutates the dependency tree
+
+deny:
+  - destructive-delete # rm -rf
+  - force-push # rewrites remote history
+  - read-secrets # .env, *.pem, credential files
+  - global-install # global package installs escape the repo

package/packages/layer1/session-handoff/commands/handoff.md

@@ -0,0 +1,185 @@
+---
+description: Capture full session context into a chronologically-named, self-contained handoff document so a fresh session can resume the work without re-running discovery.
+argument-hint: [optional-topic-slug]
+allowed-tools: Read, Glob, Grep, Bash(git status:*), Bash(git branch:*), Bash(git diff:*), Bash(git log:*), Bash(date:*), Bash(ls:*), Bash(mkdir:*), Write
+---
+
+# Session Handoff Document
+
+You are a senior engineer writing a handoff document at the end of a working
+session. Capture ALL relevant context so a fresh session — with none of this
+conversation in memory — can read the file and immediately continue the work.
+
+The handoff is a **context cache, not just a status report.** A fresh session
+(or a resume subagent whose only briefing is this file) should be able to act
+from it without re-running the discovery you already did. Provide or reference
+the load-bearing context — files, line numbers, doc sections, prior art,
+commands — rather than making the next session rediscover it.
+
+## Phase 1 — Build the filename
+
+Read the clock so the name sorts chronologically (do not guess the time):
+
+- Timestamp: !`date +%Y-%m-%d_%H%M`
+
+Build the filename `YYYY-MM-DD_HHMM_HANDOFF_<topic>.md`:
+- `<topic>` is a short kebab-case slug for the work. Use `$ARGUMENTS` if
+  provided; otherwise derive it from the task.
+- Date-and-time first means a plain alphabetical listing is chronological.
+
+## Phase 2 — Gather context
+
+Analyze this conversation for:
+- The task/feature/bug being worked on
+- Files read, created, modified, deleted
+- Key decisions and their rationale
+- Problems hit and how they were solved
+- What is done vs pending
+- Open questions and blockers
+
+Then, crucially, harvest from **your own session** the pointers a fresh session
+would otherwise have to rediscover — the files you Read, the searches you ran,
+the docs you consulted, the commands you found. These go in the *Context map &
+references* section below. Don't re-derive them; you already paid for them.
+
+## Phase 3 — Project state
+
+If in a git repo, capture current branch, staged/unstaged changes, and recent
+commits from this session:
+
+- Branch: !`git branch --show-current 2>/dev/null`
+- Status: !`git status --short 2>/dev/null`
+- Recent commits: !`git log --oneline -10 2>/dev/null`
+
+Capture verification state too: identify the project's own build/test/lint
+commands (from its config / docs / CI) and record their current result — what
+passes, what fails, what is untested. Use whatever the project actually has;
+don't assume a specific toolchain.
+
+## Phase 4 — Choose save location
+
+Save to the first of these that exists (create the dir if needed):
+1. `docs/handoffs/`
+2. `docs/`
+3. `.claude/handoffs/` (create the `handoffs` subdir)
+4. project root (fallback)
+
+Run `mkdir -p` on the chosen directory before writing.
+
+## Phase 5 — Write the document
+
+Write the file using the Write tool. NEVER just print it to chat — it must be
+saved to disk. Use this structure:
+
+````markdown
+# Handoff: [Brief Title]
+
+> **RESUMING SESSION:** If you are a fresh session reading this file, your job is
+> to continue the work described below. Read "Context Map & References" first so
+> you can act without re-running discovery, then start at "Immediate Next Steps"
+> and verify current state against the repo before proceeding.
+
+**Created:** [timestamp]
+**Branch:** [branch]
+
+## Summary
+[2–3 sentence executive summary: what was being worked on and current state.]
+
+## Context Map & References
+*The resume-time context cache — populate this so the next session skips
+re-discovery. Be generous here; a pointer that saves a re-search earns its
+bytes.*
+
+### Key files
+- `path:line-range` — why it matters (what to read / change here)
+
+### Reference material
+- [Project design/decision/architecture doc] §section — what it says that matters
+- [External link / ticket / spec] — relevance
+
+### Prior art / templates to mirror
+- `path` — the pattern to copy for the pending work
+
+### Commands
+```bash
+[exact build / test / run / lint invocations for this project]
+```
+
+### Search anchors
+- `grep/symbol/query` — what it locates (so re-search is cheap)
+
+### Critical excerpts
+[Short snippets of the few load-bearing pieces, so the next session often need
+not reopen the file.]
+
+## Work Completed
+- [ ] [Specific change 1]
+- [ ] [Specific change 2]
+
+### Key Decisions
+| Decision | Rationale | Alternatives |
+| --- | --- | --- |
+| ... | ... | ... |
+
+## Files Affected
+### Created
+- `path` — purpose
+### Modified
+- `path` — what changed and why (functions/lines if relevant)
+### Deleted
+- `path` — why
+
+## Technical Context
+[Architecture notes, patterns, new dependencies, config/env changes.]
+
+## Current State
+### Working
+- ...
+### Not working
+- [issue — suspected cause]
+### Verification
+- [ ] Build: [status]
+- [ ] Tests: [status / which command]
+- [ ] Lint/typecheck: [status]
+- [ ] Manual: [what was tested]
+
+## Immediate Next Steps
+1. [Most critical next action — be specific]
+2. [Second priority]
+3. [Third priority]
+
+## Blocked On
+- [Blocker + how to unblock]
+
+## Open Questions
+- [ ] [Question 1]
+- [ ] [Question 2]
+
+## Instruction-layer follow-up
+- [Did this session change the project in a way that makes its authored
+  instruction files (agent-instruction docs / rules) stale or incomplete? If so,
+  what needs updating — and via the project's own upkeep path, not silently.]
+````
+
+## Constraints
+- Keep the prose sections concise; the *Context Map & References* section may be
+  as long as it needs — prioritize actionable, copy-pasteable pointers over
+  narrative.
+- Use real file paths, function names, line numbers.
+- Present tense for current state, future tense for next steps.
+- The "Immediate Next Steps" and "Context Map & References" sections are
+  mandatory and must be specific.
+
+## Phase 6 — Confirm and hand off
+
+After writing, print exactly this to chat (with real values substituted):
+
+```
+✅ Handoff saved: <relative/path/to/file.md>
+
+To continue, open a NEW session and send:
+  Read <relative/path/to/file.md> and continue from the Immediate Next Steps section.
+```
+
+Do not attempt to spawn or launch another session — that is not supported in
+this environment. The user starts the next session manually.

package/packages/layer1/session-handoff/package.yaml

@@ -0,0 +1,10 @@
+# Package manifest (docs/wiki/packages-and-emit.md, D22/D24). Ships a standing reminder
+# (rules.md) plus the /praxis-handoff command (commands/handoff.md): capture full
+# session context into a chronologically-named, self-contained handoff doc so a
+# fresh agent session resumes without losing state or re-running discovery.
+# Layer 1 / stack- & tool-agnostic — the command adapts to whatever build/test,
+# design doc, and instruction layer the target project has; it hardcodes none of
+# Praxis's own specifics.
+name: session-handoff
+layer: layer1
+provides: [rules, commands]

package/packages/layer1/session-handoff/rules.md

@@ -0,0 +1,20 @@
+## Session handoff
+
+Work outlives a single session: context windows fill, tasks switch, phases
+close. Before that state is lost, capture it — so a fresh session, with none of
+the current conversation in memory, can resume without guessing or re-deriving.
+
+- Hand off at a natural boundary in a verified state — not mid-edit. Stop where
+  the build and tests are green, or where any breakage is understood and noted.
+- Write handoffs by running `/praxis-handoff`, not by hand — it produces a
+  self-contained, chronologically-named document. Treat it as the next session's
+  only briefing.
+- Make it actionable: what's done, what's pending, the single most important
+  next step, verification status, and any open decisions.
+- Carry the context forward, don't just summarize it. Reference the load-bearing
+  files (`path:line`), the relevant design-doc sections, the prior-art to mirror,
+  and the exact commands — so the next session skips re-running discovery.
+- Note instruction-layer follow-up: if the session changed the project in a way
+  that makes the authored instruction files stale or incomplete, say so.
+- Keep handoffs together in one directory so they sort in chronological order;
+  don't scatter them into the codebase.

package/packages/layer1/upkeep/commands/upkeep.md

@@ -0,0 +1,31 @@
+---
+description: Run the deterministic drift check plus the instruction-layer audit and wiki maintenance passes, and report one consolidated result.
+argument-hint: [optional-area-to-focus]
+allowed-tools: Bash(npx praxis check:*), Bash(praxis check:*)
+---
+
+Focus: $ARGUMENTS — if empty, cover all three passes at a high level.
+
+This is the single entry point for "is my methodology layer still current
+with reality?" It sequences three existing checks rather than re-implementing
+them — restating their logic here would duplicate content that drifts
+independently of its canonical home.
+
+1. **Deterministic drift.** Run `praxis check` (or `npx praxis check` if the
+   `praxis` CLI isn't on PATH), if available in this project. If it reports
+   file drift, tell the user to run `praxis sync`. If it reports managed-block
+   conflicts or broken anchors, surface them as-is. This step needs no LLM
+   judgment — do it first so the semantic passes below build on a known-good
+   baseline.
+2. **Instruction layer.** Perform the audit defined by `/praxis-audit`,
+   scoped to the focus above. Follow that command's own steps; do not
+   re-derive them here.
+3. **Wiki.** Perform the wiki maintenance defined by `/praxis-wiki`, scoped to
+   the focus above — it files newly-authored knowledge and lints existing pages,
+   and no-ops when there is nothing to do. Follow that command's own steps; do
+   not re-derive them here. (Full delegation, symmetric with the audit pass —
+   not a hand-picked phase, which would restate the skill's logic.)
+4. **Consolidated report.** Summarize across all three passes: what's in
+   sync, what drifted, what was fixed, and what still needs the user's call.
+   Both sub-passes already gate edits on user confirmation before changing
+   anything — preserve that here; this command must not bypass it.

package/packages/layer1/upkeep/package.yaml

@@ -0,0 +1,10 @@
+# Package manifest (docs/wiki/packages-and-emit.md, D29). Ships a standing reminder
+# (rules.md) plus the /praxis-upkeep command (commands/upkeep.md): one entry point
+# that runs the deterministic `praxis check` drift gate and then both semantic-drift
+# passes — the instruction-layer audit (/praxis-audit) and the wiki lint
+# (/praxis-wiki Phase 4) — and reports one consolidated result. Layer 1 /
+# stack- & tool-agnostic; defers to those two commands rather than restating
+# their steps, so the detail can't drift independently of its canonical home.
+name: upkeep
+layer: layer1
+provides: [rules, commands]

package/packages/layer1/upkeep/rules.md

@@ -0,0 +1,12 @@
+## Upkeep
+
+The methodology layer (instruction files, the knowledge wiki, the emitted
+`.claude/` files) drifts from project reality the same way code drifts from
+docs. When work reveals that drift — a stale instruction, a wiki page that no
+longer matches the code, an unsynced emit — or when work produces new durable
+knowledge to file (a decision, a new package), run `/praxis-upkeep` rather than
+letting the gap persist, fixing it ad hoc, or invoking the sub-skills piecemeal.
+It is the single front gate: it sequences `praxis check` and fully delegates to
+`/praxis-audit` (instruction layer) and `/praxis-wiki` (knowledge wiki). The
+command itself only sequences and reports; the sub-skills make any edits, each
+behind its own confirmation gate.

package/packages/layer1/wiki-memory/commands/wiki.md

@@ -0,0 +1,103 @@
+---
+description: Bootstrap, update, or lint the project knowledge wiki — a durable, in-repo, linked-markdown memory the agent reads at the start of work and maintains as the project changes (Karpathy "LLM wiki" pattern).
+argument-hint: [optional-topic-to-focus]
+allowed-tools: Read, Glob, Grep, Bash(git log:*), Bash(git diff:*), Bash(ls:*), Bash(mkdir:*), Bash(date:*), Write, Edit
+---
+
+# Project knowledge wiki
+
+You are curating a durable knowledge wiki for this project: linked markdown pages
+of long-lived knowledge that a future session reads instead of re-deriving. This
+is the agent's cross-session memory **of the project** — version-controlled and
+shared with the team. It is NOT a per-session handoff (transient — that is
+`/praxis-handoff`) and NOT the authored instruction layer (`CLAUDE.md`,
+`.claude/rules` — that is `/praxis-audit`).
+
+The wiki has two kinds of durable knowledge:
+- **Derived summaries** compress code, config, and canonical docs. The underlying
+  source wins on conflict; fix the wiki.
+- **Canonical intent** records decisions, rationale, scope, and design intent —
+  the "why" that is not fully derivable from code. When code and canonical intent
+  diverge, surface the drift for human judgment instead of silently overwriting
+  one with the other.
+
+Focus: $ARGUMENTS — if empty, refresh and lint the whole wiki at a high level.
+
+## Phase 1 — Locate or create the wiki
+
+Use the first of these that already exists; otherwise create the first one
+(run `mkdir -p` before writing):
+1. `docs/wiki/`
+2. `wiki/`
+3. `.praxis/wiki/`
+
+- Existing entries: !`ls -R docs/wiki wiki .praxis/wiki 2>/dev/null || true`
+- Today (for log entries, do not guess): !`date +%Y-%m-%d`
+
+Front the wiki with two entry-point files; create them if missing:
+- `index.md` — a catalog of every page: a link and a one-line summary each.
+- `log.md` — an append-only record of wiki changes, newest last, each entry dated
+  (e.g. `## [YYYY-MM-DD] <added|updated|removed> — <page>: <why>`).
+
+## Phase 2 — Ingest durable knowledge
+
+Gather long-lived facts a future session would otherwise have to re-derive:
+- Architecture and how the parts fit; key directories/modules and their roles.
+- Hard-won gotchas, non-obvious constraints, and their underlying cause.
+- Workflows — build/test/run/release — and the *why* behind any unusual step.
+- Decisions and their rationale. Keep a single canonical `decisions.md` ledger
+  when decisions are numbered or cited from code/docs: append-only, never
+  renumbered, never scattered across topic pages.
+- Useful answers or analyses derived in this session — file them back so they
+  don't vanish into chat history.
+
+Sources: the code and config, existing docs, recent git history (`git log`,
+changed files), and what was learned in this session. Capture **durable**
+knowledge only — not transient session state, not the instruction rules. Never
+invent a fact that isn't backed by the code, config, a canonical doc, or the
+user's answer. When unsure, ask rather than guess.
+
+## Phase 3 — Write entries and update index + log
+
+- One topic per page; a short, linkable page beats a sprawling document.
+- Update the existing canonical page instead of creating a near-duplicate.
+- Cross-link related pages so retrieval is "read the index → follow the links."
+- Keep the taxonomy obvious: `orientation.md` as the map, focused design/topic
+  entries, one `decisions.md` ledger when needed, `workflows.md` for commands, and
+  `gotchas.md` for traps with causes.
+- Prefer linking a canonical source over restating it (restated facts drift).
+- Add or update `praxisAnchors` frontmatter for the canonical sources a page
+  depends on. Phase-2 anchors are page-level and deterministic only:
+  - `type: path`, `target: repo/relative/path`
+  - `type: command`, `target: npm run <script>` or `npm <script>`
+  - `type: section`, `target: docs/file.md#heading-slug`
+  Keep staleness/hash tripwires out for now; those are future advisory signals.
+- Update `index.md` so every page is listed and reachable, and append a `log.md`
+  entry for each change.
+
+## Phase 4 — Lint
+
+Health-check the wiki and fix what you can (ask before large deletions):
+- **Contradictions** — derived summaries that disagree with current code/config
+  lose to the source; fix the wiki. Canonical-intent entries are different: if
+  code and intent diverge, report the drift and route it to a decision/update
+  step (or `/praxis-audit` for instruction-layer changes) instead of deciding
+  automatically. Two wiki entries that disagree resolve to the more recent /
+  authoritative / better-supported claim, with the resolution noted.
+- **Stale claims** — derived facts the current code has invalidated: fix or
+  remove them. For canonical-intent drift, preserve the intent and report the
+  mismatch for human judgment.
+- **Orphan pages** — pages not linked from the index or any other page: link or
+  retire them.
+- **Missing cross-references** — related pages that don't link each other: connect
+  them.
+- **Broken anchors** — run `praxis check` if available; fix any
+  `praxisAnchors` entry whose path, command, or section no longer resolves.
+
+## Phase 5 — Report
+
+Print what you created, updated, and removed (with paths), the lint issues found
+and how you resolved them, and name the single most useful entry a fresh session
+should read first.
+
+Ask before large rewrites or deletions — show the list and confirm.

package/packages/layer1/wiki-memory/package.yaml

@@ -0,0 +1,10 @@
+# Package manifest (docs/wiki/packages-and-emit.md, D25). Ships a standing reminder (rules.md)
+# plus the /praxis-wiki command (commands/wiki.md): maintain a durable, in-repo,
+# linked-markdown knowledge wiki the agent reads at the start of work and updates
+# as the project changes — the agent's cross-session memory of the project,
+# delivered as curated declarative files (D8's in-scope side), never a runtime
+# backend (docs/wiki/gotchas.md/D12). Layer 1 / stack- & tool-agnostic; adapts to whatever the
+# target project has and hardcodes none of Praxis's own specifics.
+name: wiki-memory
+layer: layer1
+provides: [rules, commands]

package/packages/layer1/wiki-memory/rules.md

@@ -0,0 +1,49 @@
+## Wiki memory
+
+Knowledge outlives a single conversation. An agent that re-derives the same
+project facts every session wastes effort and drifts. Keep a durable, in-repo
+**knowledge wiki** — linked markdown pages of long-lived knowledge that a fresh
+session reads instead of rediscovering (the Karpathy "LLM wiki" pattern). Because
+it lives in the repo, it is version-controlled and shared with the whole team,
+unlike a tool's machine-local native memory.
+
+- **Two entry points.** Front the wiki with an `index.md` that lists every page
+  with a one-line summary and a link, and a `log.md` that records — append-only —
+  what changed in the wiki and when. Read the index first; it is the map.
+- **Add a glossary when terms collide.** When a project reuses a common word for
+  a project-specific meaning, or coins its own vocabulary, keep a `glossary.md`
+  of short term definitions — each pointing to the canonical source that owns
+  it. The signal you already needed the page is one ambiguous term re-explained
+  in scattered prose. Define what a term *is* and, where the word misleads, what
+  it is *not*.
+- **Know which kind of entry you are editing.** Derived summaries compress code,
+  config, and canonical docs; the underlying source wins on conflict. Canonical
+  intent entries record decisions, rationale, scope, and design intent; when code
+  and intent diverge, surface the drift for human judgment instead of silently
+  overwriting one with the other.
+- **Keep decisions in one ledger when they are numbered or cited.** Use a single
+  canonical `decisions.md`, append new `D<N>` rows, never renumber, and never
+  scatter numbered decisions across topic pages.
+- An entry captures *durable* knowledge: architecture and how the parts fit, a
+  hard-won gotcha and its cause, a workflow, a decision and its why. Not transient
+  session state (that is a handoff) and not the authored instruction rules (those
+  are `CLAUDE.md`/`.claude/rules`).
+- At the start of a task, read the index and follow the links that bear on the
+  work — act on what is already known rather than re-deriving it.
+- When you learn something durable — including a useful answer or analysis you
+  derived mid-session — add or update an entry, link it from the index, and note
+  the change in the log. Prefer one topic per page, cross-linked, over a sprawling
+  document; update the canonical page rather than create a near-duplicate.
+- Add machine-checkable `praxisAnchors` frontmatter for canonical sources when a
+  page depends on them: `path`, `command`, and `section` anchors are hard-checked
+  by `praxis check`; staleness/hash tripwires remain advisory future work.
+- Keep it true. Periodically **lint** the wiki (via `/praxis-wiki`): flag and fix
+  contradictions, stale claims, orphan pages, and missing cross-references. A
+  stale wiki misleads worse than none. Link the canonical source rather than
+  restating it; restated facts drift independently of their source.
+- Never record a fact that isn't backed by the code, config, a canonical doc, or
+  the user — the wiki is curated knowledge, not speculation.
+- Do wiki work by running `/praxis-wiki`, not by hand — bootstrapping, filing new
+  knowledge, and linting all run the skill rather than hand-authoring pages and
+  hand-editing `index.md`/`log.md` around it. It keeps the index, log, and anchors
+  consistent.

package/packages/layer2/node-recipes/package.yaml

@@ -0,0 +1,10 @@
+# Package manifest (docs/wiki/packages-and-emit.md). Layer 2: stack-specific,
+# domain-agnostic authoring recipes for TypeScript/Node codebases — "how to add a
+# module/feature well here" — that point at the target repo's own in-repo prior art
+# for the concrete shape rather than shipping code. Craft, not domain: portable
+# across any Node project; hardcodes none of a project's specifics. Applies only
+# when praxis.yaml declares the `node` stack.
+name: node-recipes
+layer: layer2
+stack: node
+provides: [rules]

package/packages/layer2/node-recipes/rules.md

@@ -0,0 +1,33 @@
+---
+paths: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.mjs"]
+---
+
+## Node/TypeScript authoring recipes (Layer 2)
+
+Stack-specific craft for TypeScript/Node code. These say *how to add something
+well in this stack*; the concrete shape lives in this repo's own prior art, not
+here. Find the nearest existing example and mirror it.
+
+- **Mirror the nearest module.** Before adding a feature, open the closest
+  existing file that already does the same kind of thing (a sibling in the same
+  directory, an adjacent route/command/service). Copy its structure — imports,
+  exports, error handling, naming — rather than inventing a new shape. The
+  prior art is the template; matching it is verifiable, following prose is not.
+- **One module, one responsibility.** A new `.ts` file exports the smallest
+  coherent unit. Keep pure logic separate from I/O (filesystem, network, process)
+  so the logic is testable without mocks — mirror how the existing modules here
+  already split the two.
+- **Use the platform and installed deps before adding one.** Node stdlib (`node:fs`,
+  `node:path`, `node:crypto`, `fetch`) and a dependency already in
+  `package.json` cover most needs. A new dependency for what a few lines do is
+  debt; justify it against what is already imported in neighbouring files.
+- **Types are the contract.** Type the inputs and outputs at module boundaries;
+  validate external/untrusted input where it enters (a schema validator if the
+  repo already uses one, e.g. zod). Don't re-validate data already typed and
+  checked upstream.
+- **Surgical change.** Touch only what the task needs; match the surrounding
+  style and the repo's lint/format config. Don't reformat or "improve" adjacent
+  code. Every changed line should trace to the task.
+- **ESM vs CJS, follow the repo.** Match the module system, import extensions
+  (`.js` specifiers under `"type": "module"`), and `tsconfig` target already in
+  use — don't introduce a second convention.

package/packages/layer2/node-testing/package.yaml

@@ -0,0 +1,10 @@
+# Package manifest (docs/wiki/packages-and-emit.md). Layer 2: a stack-specific
+# decision recipe for TypeScript/Node codebases — how to choose the right test
+# layer (unit vs integration/conformance) and honour the harness-before-features
+# ordering — pointing at the target repo's own test suites for the concrete shape.
+# Craft, not domain: portable across any Node project. Applies only when
+# praxis.yaml declares the `node` stack.
+name: node-testing
+layer: layer2
+stack: node
+provides: [rules]

package/packages/layer2/node-testing/rules.md

@@ -0,0 +1,33 @@
+---
+paths: ["**/*.ts", "**/*.tsx", "**/*.test.ts", "**/*.spec.ts"]
+---
+
+## Node/TypeScript test-layer recipe (Layer 2)
+
+Choosing *where* a test belongs matters as much as writing it. Pick the layer
+that fails for the right reason, and mirror the repo's existing tests of that
+kind for structure and fixtures.
+
+- **Harness before features.** A rule that matters has a test. Write (or extend)
+  the test that pins the new behaviour *before or with* the code that satisfies
+  it — never land logic whose only check is "it looked right". Make the failing
+  test the prompt: it states what is missing.
+- **Pick the layer by what could break.**
+  - *Unit* — pure logic, branches, parsing, a single module's contract. Fast, no
+    I/O, no fixtures. Default here; most logic belongs at this layer.
+  - *Integration* — two or more modules composed, or real I/O (filesystem, a
+    spawned process, a built artifact). Use when the bug would live in the seam
+    between units, not inside one.
+  - *Conformance / end-to-end* — an invariant the whole tool must honour, or a
+    contract a future change must not break. Use for the rails, not for every
+    feature.
+- **Mirror the existing suite.** Find the nearest test of the same layer and copy
+  its setup — the test runner already in `package.json` (e.g. vitest/jest), its
+  file location and naming convention, how it builds fixtures and asserts. Don't
+  introduce a second runner or a new fixture style.
+- **Assert behaviour, not implementation.** Test observable inputs→outputs and
+  error cases at the boundary; avoid asserting private internals that refactors
+  will churn. One clear failing assertion beats five brittle ones.
+- **No new framework for one test.** The repo's installed runner and plain
+  assertions cover almost everything. Reach for a new testing dependency only
+  when the existing one demonstrably cannot express the check.

package/packages/layer2/python-backend-recipes/package.yaml

@@ -0,0 +1,10 @@
+# Package manifest (docs/wiki/packages-and-emit.md). Layer 2: stack-specific,
+# domain-agnostic authoring recipes for Python backend codebases — "how to add a
+# module/feature well here" — that point at the target repo's own in-repo prior art
+# for the concrete shape rather than shipping code. Craft, not domain: portable
+# across any Python project; hardcodes none of a project's specifics. Applies only
+# when praxis.yaml declares the `python-backend` stack.
+name: python-backend-recipes
+layer: layer2
+stack: python-backend
+provides: [rules]