feat: add default permissions to ctx init and prompting guide

ctx init now pre-seeds permissions for all ctx commands in
settings.local.json, so /ctx-* slash commands work out of the box.
Permissions are merged additively to preserve user customizations.

Also adds:
- Prompting guide documentation (docs/prompting-guide.md)
- make site-setup, site, site-serve targets for documentation

Signed-off-by: Jose Alekhinne <alekhinejose@gmail.com>

Author: josealekhine

.context/LEARNINGS.md

@@ -348,3 +348,5 @@ directory component (e.g., `/home/user/ctx/internal/...`).
 - **[2026-01-26-0553]** Claude Code settings.local.json hook keys are 'PreToolUse' and 'SessionEnd' (not 'PreToolUseHooks'/'SessionEndHooks'). The 'Hooks' suffix causes 'Invalid key in record' errors.
 
 - **[2026-01-26-0612]** Go's json.Marshal escapes `>`, `<`, and `&` as unicode (\u003e, \u003c, \u0026) by default for HTML safety. Use json.Encoder with SetEscapeHTML(false) when generating config files that contain shell commands like `2>/dev/null`.
+
+- **[2026-01-27-054706]** Claude Code slash commands using `!` bash syntax require matching permissions in settings.local.json. When adding new /ctx-* commands, ensure ctx init pre-seeds the required Bash(ctx <subcommand>:*) permissions. Use additive merging for user config - never remove existing permissions.

Makefile

@@ -2,7 +2,7 @@
 #
 # Common targets for Go developers
 
-.PHONY: build test vet fmt lint clean all release build-all dogfood help test-coverage smoke
+.PHONY: build test vet fmt lint clean all release build-all dogfood help test-coverage smoke site site-serve site-setup
 
 # Default binary name and output
 BINARY := ctx
@@ -114,6 +114,20 @@ install:
 	cp $(BINARY) /usr/local/bin/$(BINARY)
 	@echo "Installed ctx to /usr/local/bin/ctx"
 
+## site-setup: Create venv and install zensical
+site-setup:
+	python3 -m venv .venv
+	.venv/bin/pip install --upgrade pip
+	.venv/bin/pip install zensical
+
+## site: Build documentation site
+site:
+	.venv/bin/zensical build
+
+## site-serve: Serve documentation site locally
+site-serve:
+	.venv/bin/zensical serve
+
 ## help: Show this help
 help:
 	@echo "Context CLI - Available targets:"

docs/index.md

@@ -215,6 +215,7 @@ ctx drift
 
 ## Next Steps
 
+- [Prompting Guide](prompting-guide.md) — Effective prompts for AI sessions
 - [CLI Reference](cli-reference.md) — All commands and options
 - [Context Files](context-files.md) — File formats and structure
 - [Ralph Loop Integration](ralph-loop.md) — Autonomous AI development workflows

docs/prompting-guide.md

@@ -0,0 +1,233 @@
+---
+#   /    Context:                     https://ctx.ist
+# ,'`./    do you remember?
+# `.,'\
+#   \    Copyright 2026-present Context contributors.
+#                 SPDX-License-Identifier: Apache-2.0
+
+title: Prompting Guide
+icon: lucide/message-circle
+---
+
+![ctx](images/ctx-banner.png)
+
+## Prompting Guide
+
+Effective prompts for working with AI assistants in ctx-enabled projects.
+
+### Why This Matters
+
+AI assistants don't automatically read context files. The right prompt triggers
+the right behavior. This guide documents prompts that reliably produce good results.
+
+---
+
+## Session Start
+
+### "Do you remember?"
+
+**What it does**: Triggers the AI to read AGENT_PLAYBOOK, CONSTITUTION, sessions/,
+and other context files before responding.
+
+**When to use**: Start of every important session.
+
+```
+Do you remember what we were working on?
+```
+
+**Why it works**: The question implies prior context exists. The AI checks files
+rather than admitting ignorance.
+
+### "What's the current state?"
+
+**What it does**: Prompts reading of TASKS.md, recent sessions, and status overview.
+
+**When to use**: Resuming work after a break.
+
+**Variants**:
+
+- "Where did we leave off?"
+- "What's in progress?"
+- "Show me the open tasks"
+
+---
+
+## During Work
+
+### "Why doesn't X work?"
+
+**What it does**: Triggers root cause analysis rather than surface-level fixes.
+
+**When to use**: When something fails unexpectedly.
+
+**Why it works**: Framing as "why" encourages investigation before action.
+The AI will trace through code, check configurations, and identify the actual cause.
+
+!!! example "Real example"
+    "Why can't I run /ctx-save?" led to discovering missing permissions
+    in settings.local.json bootstrapping—a fix that benefited all users.
+
+### "Is this consistent with our decisions?"
+
+**What it does**: Prompts checking DECISIONS.md before implementing.
+
+**When to use**: Before making architectural choices.
+
+**Variants**:
+
+- "Check if we've decided on this before"
+- "Does this align with our conventions?"
+
+### "What would break if we..."
+
+**What it does**: Triggers defensive thinking and impact analysis.
+
+**When to use**: Before making significant changes.
+
+```
+What would break if we change the Settings struct?
+```
+
+### "Before you start, read X"
+
+**What it does**: Ensures specific context is loaded before work begins.
+
+**When to use**: When you know relevant context exists in a specific file.
+
+```
+Before you start, read .context/sessions/2026-01-20-auth-discussion.md
+```
+
+---
+
+## Reflection & Persistence
+
+### "What did we learn?"
+
+**What it does**: Prompts reflection on the session and often triggers adding
+learnings to LEARNINGS.md.
+
+**When to use**: After completing a task or debugging session.
+
+**Why it works**: Explicit reflection prompt. The AI will summarize insights
+and often offer to persist them.
+
+### "Add this as a learning/decision"
+
+**What it does**: Explicit persistence request.
+
+**When to use**: When you've discovered something worth remembering.
+
+```
+Add this as a learning: "JSON marshal escapes angle brackets by default"
+```
+
+### "Save context before we end"
+
+**What it does**: Triggers context persistence before session close.
+
+**When to use**: End of session, or before switching topics.
+
+**Variants**:
+
+- "Let's persist what we did"
+- "Update the context files"
+- `/ctx-save` (slash command in Claude Code)
+
+---
+
+## Exploration & Research
+
+### "Explore the codebase for X"
+
+**What it does**: Triggers thorough codebase search rather than guessing.
+
+**When to use**: When you need to understand how something works.
+
+**Why it works**: "Explore" signals that investigation is needed, not immediate action.
+
+### "How does X work in this codebase?"
+
+**What it does**: Prompts reading actual code rather than explaining general concepts.
+
+**When to use**: Understanding existing implementation.
+
+```
+How does session saving work in this codebase?
+```
+
+### "Find all places where X"
+
+**What it does**: Comprehensive search across the codebase.
+
+**When to use**: Before refactoring or understanding impact.
+
+---
+
+## Meta & Process
+
+### "What should we document from this?"
+
+**What it does**: Prompts identifying learnings, decisions, and conventions
+worth persisting.
+
+**When to use**: After complex discussions or implementations.
+
+### "Is this the right approach?"
+
+**What it does**: Invites the AI to challenge the current direction.
+
+**When to use**: When you want a sanity check.
+
+**Why it works**: Gives permission to disagree. AIs often default to agreeing;
+this prompt signals you want honest assessment.
+
+### "What am I missing?"
+
+**What it does**: Prompts thinking about edge cases, overlooked requirements,
+or unconsidered approaches.
+
+**When to use**: Before finalizing a design or implementation.
+
+---
+
+## Anti-Patterns
+
+Prompts that tend to produce poor results:
+
+| Prompt | Problem | Better Alternative |
+|--------|---------|-------------------|
+| "Fix this" | Too vague, may patch symptoms | "Why is this failing?" |
+| "Make it work" | Encourages quick hacks | "What's the right way to solve this?" |
+| "Just do it" | Skips planning | "Plan this, then implement" |
+| "You should remember" | Confrontational | "Do you remember?" |
+| "Obviously..." | Discourages questions | State the requirement directly |
+
+---
+
+## Quick Reference
+
+| Goal | Prompt |
+|------|--------|
+| Load context | "Do you remember?" |
+| Resume work | "What's the current state?" |
+| Debug | "Why doesn't X work?" |
+| Validate | "Is this consistent with our decisions?" |
+| Impact analysis | "What would break if we..." |
+| Reflect | "What did we learn?" |
+| Persist | "Add this as a learning" |
+| Explore | "How does X work in this codebase?" |
+| Sanity check | "Is this the right approach?" |
+| Completeness | "What am I missing?" |
+
+---
+
+## Contributing
+
+Found a prompt that works well?
+[Open an issue](https://github.com/ActiveMemory/ctx/issues) or PR with:
+
+1. The prompt text
+2. What behavior it triggers
+3. When to use it
+4. Why it works (optional but helpful)

internal/claude/embed.go

@@ -79,6 +79,24 @@ func GetCommand(name string) ([]byte, error) {
 	return content, nil
 }
 
+// CreateDefaultPermissions returns the default permissions for ctx commands.
+//
+// These permissions allow Claude Code to run ctx CLI commands without
+// prompting for approval. All ctx subcommands are pre-approved.
+//
+// Returns:
+//   - []string: List of permission patterns for ctx commands
+func CreateDefaultPermissions() []string {
+	return []string{
+		"Bash(ctx status:*)",
+		"Bash(ctx agent:*)",
+		"Bash(ctx add:*)",
+		"Bash(ctx session:*)",
+		"Bash(ctx tasks:*)",
+		"Bash(ctx loop:*)",
+	}
+}
+
 // CreateDefaultHooks returns the default ctx hooks configuration for
 // Claude Code.
 //

internal/claude/embed_test.go

@@ -142,16 +142,43 @@ func TestSettingsStructure(t *testing.T) {
 	// Test that Settings struct can be instantiated correctly
 	settings := Settings{
 		Hooks: CreateDefaultHooks(""),
-		Permissions: map[string]interface{}{
-			"allow": []string{"read", "write"},
+		Permissions: PermissionsConfig{
+			Allow: []string{"Bash(ctx status:*)", "Bash(ctx agent:*)"},
 		},
 	}
 
 	if len(settings.Hooks.PreToolUse) == 0 {
 		t.Error("Settings.Hooks.PreToolUse should not be empty")
 	}
 
-	if settings.Permissions == nil {
-		t.Error("Settings.Permissions should not be nil")
+	if len(settings.Permissions.Allow) == 0 {
+		t.Error("Settings.Permissions.Allow should not be empty")
+	}
+}
+
+func TestCreateDefaultPermissions(t *testing.T) {
+	perms := CreateDefaultPermissions()
+
+	if len(perms) == 0 {
+		t.Error("CreateDefaultPermissions should return permissions")
+	}
+
+	// Check that essential ctx commands are included
+	expected := []string{
+		"Bash(ctx status:*)",
+		"Bash(ctx agent:*)",
+		"Bash(ctx add:*)",
+		"Bash(ctx session:*)",
+	}
+
+	permSet := make(map[string]bool)
+	for _, p := range perms {
+		permSet[p] = true
+	}
+
+	for _, e := range expected {
+		if !permSet[e] {
+			t.Errorf("Missing expected permission: %s", e)
+		}
 	}
 }

internal/claude/types.go

@@ -43,14 +43,23 @@ type Hook struct {
 	Command string `json:"command"`
 }
 
+// PermissionsConfig represents the permissions section of Claude Code's
+// settings.local.json.
+//
+// Fields:
+//   - Allow: List of tool patterns that are pre-approved (e.g., "Bash(ctx status:*)")
+type PermissionsConfig struct {
+	Allow []string `json:"allow,omitempty"`
+}
+
 // Settings represents the full Claude Code settings.local.json structure.
 //
 // This is used when reading or writing project-level Claude Code configuration.
 //
 // Fields:
 //   - Hooks: Hook configuration for lifecycle events
-//   - Permissions: Tool permission overrides (key: tool pattern, value: permission)
+//   - Permissions: Tool permission configuration
 type Settings struct {
-	Hooks       HookConfig             `json:"hooks,omitempty"`
-	Permissions map[string]interface{} `json:"permissions,omitempty"`
+	Hooks       HookConfig        `json:"hooks,omitempty"`
+	Permissions PermissionsConfig `json:"permissions,omitempty"`
 }