feat: add AGENTS.md for agent self-maintenance + github_repo config injection

- Create AGENTS.md with comprehensive project context for agent self-maintenance
  (source layout, conventions, build/test, adding tools/flags/model profiles, security)
- Add github_repo_directory and github_repo_url config fields (CLI flags, env vars,
  JSON config, system prompt injection) so the agent knows its own repository location
- Fix TestLoadProjectFile_Missing to use temp dir (was failing with AGENTS.md present)
- Fix TestConfigSystemMessage to use NoProjectFile: true

All 16 test packages pass.

Author: jkyberneees

AGENTS.md

@@ -0,0 +1,158 @@
+# odek — Agent Maintenance Guide
+
+This file is automatically loaded by odek when running inside this repository.
+It provides context about the project's architecture, conventions, and how to update/maintain it.
+
+---
+
+## Project Identity
+
+- **Package:** `odek` (Go module: `github.com/BackendStack21/kode`)
+- **What it is:** Minimal Go autonomous agent runtime — ReAct (Reasoning + Acting) loop with zero external dependencies (stdlib only).
+- **Binary:** `odek` — single static binary, ~11 MB, instant startup.
+- **Config:** Layered priority: `~/.odek/config.json` → `./odek.json` → `ODEK_*` env vars → CLI flags.
+
+## Source Layout
+
+```
+odek.go                       Public API (Config, New, Run, Close, ModelProfile, KnownProfiles)
+odek_test.go                  Tests for public API
+cmd/odek/
+  main.go                     CLI entry point, flag parsing, commands, sandbox
+  shell.go                    Built-in shell tool (local or docker exec)
+  serve.go                    Web UI server (HTTP + WebSocket)
+  subagent.go                 Sub-agent command (--goal, --context, --task)
+  subagent_tool.go            delegate_tasks built-in tool
+  ui/index.html               Single-page Web UI (~770 LOC, vanilla JS + CSS)
+  *_test.go                   CLI, subagent, contract, and E2E tests
+internal/
+  config/loader.go            Config file loading, env vars, priority merge
+  llm/client.go               OpenAI-compatible HTTP client
+  loop/loop.go                ReAct engine (observe → think → act → repeat)
+  session/session.go          Session store (CRUD, trim, cleanup)
+  render/render.go            Terminal output with model label and color
+  resource/resource.go        @-reference resolver (files, sessions)
+  ws/ws.go                    RFC 6455 WebSocket framing (~200 LOC)
+  tool/registry.go            Thread-safe tool registry, clarify.go
+  danger/classifier.go        Command/URL classification for security gating
+  memory/                     MemoryManager (facts, buffer, episodes, merge, scan)
+  skills/                     Skill system (types, loader, triggers, self-improve, curator, import)
+  telegram/                   Telegram bot client, poller, handler, commands
+docs/                         Documentation (CLI, API, CONFIG, MCP, MEMORY, etc.)
+```
+
+## How It Works
+
+1. **Agent Loop (`internal/loop/loop.go`):** ReAct cycle: observe → think → act → repeat.
+   - LLM returns a tool call or final answer.
+   - Tools execute and return results.
+   - Max 90 iterations by default (`--max-iter`).
+2. **Tools:** Built-in: `read_file`, `write_file`, `search_files`, `patch`, `shell`, `browser`, `memory`, `clarify`, `delegate_tasks`. All gated by the `danger` security classifier.
+3. **Skills:** Trigger-matched `SKILL.md` files loaded on-demand. Auto-learns from patterns every session. Stored in `~/.odek/skills/` and `./.odek/skills/`.
+4. **Memory:** Three tiers — facts (durable entries), session buffer (turn summaries), episodes (LLM-extracted knowledge). Uses go-vector RandomProjections for merge-on-write.
+5. **Sub-agents:** `delegate_tasks` spawns real OS subprocesses via `odek subagent`. Each gets a fresh agent process with its own config.
+
+## Key Conventions
+
+- **Zero-dependency policy:** No external Go modules beyond stdlib. All contributions must maintain this.
+- **Tests:** 1760+ tests, run with `go test ./...` (no network, no Docker needed for unit tests).
+- **Error handling:** Return errors, don't panic. Fatal errors go through `fmt.Fprintf(os.Stderr, ...)`.
+- **Config structs:** JSON tags for serialization. `*bool` for optional tristate fields (nil = not set).
+- **Security:** Symlinked AGENTS.md is refused. Shell commands are classified into 8 risk classes. Sandbox mode uses Docker with no network and read-only mounts.
+- **Model profiles:** Added in `odek.go`'s `KnownProfiles` var. Longest-prefix matching.
+
+## How to Update/Maintain This Project
+
+### Building
+
+```bash
+go build -o bin/odek ./cmd/odek     # build binary
+go build ./...                       # check compilation
+```
+
+### Testing
+
+```bash
+go test ./... -count=1               # all unit tests
+go test -race ./... -count=1         # with race detector
+go test -v ./internal/session/       # specific package
+KODE_E2E=true go test ./cmd/odek/ -run "TestE2E_"  # E2E tests
+```
+
+### Adding a New Model Profile
+
+Edit `odek.go`, add to `KnownProfiles`:
+```go
+{
+    Prefix: "my-model",
+    Profile: ModelProfile{
+        Label:           "My Model",
+        DefaultThinking: "enabled",
+        Timeout:         120,
+        MaxContext:      128_000,
+    },
+},
+```
+
+### Adding a New Tool
+
+1. Create the tool struct in `cmd/odek/` or `internal/tool/`.
+2. Implement `Name()`, `Description()`, `Schema()`, `Call(args string) (string, error)`.
+3. Register in `registerBuiltinTools()` in `cmd/odek/main.go`.
+4. Add security classification in `internal/danger/classifier.go` if it runs shell commands.
+5. Add tests.
+
+### Adding a New Command/Flag
+
+1. Define the flag in `main.go`'s `flags` struct.
+2. Parse in `parseFlags()`.
+3. Wire through `resolveConfig()` into the resolved config.
+4. Pass to `odek.New()` or the relevant handler.
+5. Document in `docs/CLI.md` and `docs/CONFIG.md`.
+6. Add env var support in `internal/config/loader.go`.
+
+### Documentation
+
+- All docs are Markdown in `/docs/`.
+- `docs/CLI.md` — CLI reference (commands, flags, error codes).
+- `docs/API.md` — Programmatic API with Go examples.
+- `docs/CONFIG.md` — Configuration system.
+- `docs/DEVELOPMENT.md` — Building, testing, contributing.
+- Update docs when adding/changing features.
+
+### Skill System Maintenance
+
+- Skills live in `~/.odek/skills/` and `./.odek/skills/` as `SKILL.md` files with YAML frontmatter.
+- Learning is on by default (`--no-learn` to disable).
+- Use `odek skill curate` to audit quality/overlap.
+- Use `odek skill import <uri>` to import from URLs.
+
+### Memory System
+
+- Facts: `~/.odek/memory/user.md` and `~/.odek/memory/env.md`.
+- Episodes: Stored as JSON files in `~/.odek/memory/episodes/`.
+- Buffer: Ring buffer of turn summaries, stored in `~/.odek/memory/buffer.json`.
+- Use the `memory` tool (6 actions: read, add, replace, remove, consolidate, search).
+
+### Security Considerations
+
+- **Prompt injection:** Identity anchoring anchors agent identity at the start of the system prompt. Anti-injection rules applied on top. AGENTS.md comes after identity.
+- **Symlink protection:** `LoadProjectFile()` refuses symlinks.
+- **Sandbox:** `--sandbox` flag runs in Docker with no network, no host mounts beyond working dir, zero capabilities.
+- **Danger classifier:** Commands classified into 8 risk classes. Configurable via `dangerous` config section.
+
+### Release Process
+
+1. Update version tag: `git tag v0.x.y`
+2. Build cross-platform: `make build-all`
+3. Run full test suite: `make test-all`
+4. Push tag: `git push origin v0.x.y`
+
+## Common Gotchas
+
+- When modifying `Config` struct in `odek.go`, also update `internal/config/loader.go` (CLI flags, env vars, JSON serialization).
+- When adding to KnownProfiles, ensure tests in `odek_test.go` cover the new profile.
+- The Web UI (`cmd/odek/ui/index.html`) is embedded — rebuild the binary to see UI changes.
+- Session files are JSON in `~/.odek/sessions/` — corrupt data is handled gracefully with fallback scan.
+- The Telegram bot uses long-polling (no webhooks), built on stdlib `net/http`.
+- `delegate_tasks` sub-agents have a 120s default timeout. Override via `subagent.timeout_seconds` config.

cmd/odek/main.go

@@ -192,6 +192,10 @@ type runFlags struct {
 	SandboxCPUs     string // CPU limit (e.g. "0.5", "2")
 	SandboxUser     string // Container user (e.g. "1000:1000")
 	SandboxReadonly *bool  // nil = not set; true = read-only mount
+
+	// Repo context flags
+	GithubRepoDirectory string // --github-repo-dir
+	GithubRepoUrl       string // --github-repo-url
 }
 
 // parseRunFlags parses `odek run` arguments and returns the parsed flags.
@@ -257,6 +261,12 @@ func parseRunFlags(args []string) (runFlags, error) {
 		case "--sandbox-user":
 			f.SandboxUser = args[i+1]
 			i += 2
+		case "--github-repo-dir":
+			f.GithubRepoDirectory = args[i+1]
+			i += 2
+		case "--github-repo-url":
+			f.GithubRepoUrl = args[i+1]
+			i += 2
 		case "--ctx", "-c":
 			f.Ctx = strings.Split(args[i+1], ",")
 			i += 2
@@ -463,6 +473,7 @@ const defaultConfigTemplate = `{
   "no_color": false,
   "no_agents": false,
   "system": "",
+  "github_repo_directory": "",
   "sandbox_image": "",
   "sandbox_network": "bridge",
   "sandbox_readonly": false,
@@ -588,6 +599,7 @@ func initConfig(args []string) error {
 	fmt.Println("    no_color        Disable colored output (true/false)")
 	fmt.Println("    no_agents       Skip AGENTS.md (true/false)")
 	fmt.Println("    system          System prompt override")
+	fmt.Println("    github_repo_directory  Local clone path of the project repo")
 	fmt.Println("    sandbox_image   Docker image (alpine:latest if empty)")
 	fmt.Println("    sandbox_network Network mode (bridge | none | host)")
 	fmt.Println("    sandbox_readonly Mount working directory read-only")
@@ -719,6 +731,9 @@ func run(args []string) error {
 		SandboxMemory:   f.SandboxMemory,
 		SandboxCPUs:     f.SandboxCPUs,
 		SandboxUser:     f.SandboxUser,
+
+		GithubRepoDirectory: f.GithubRepoDirectory,
+		GithubRepoUrl:       f.GithubRepoUrl,
 	})
 
 	// Resolve @references and --ctx file attachments in the task
@@ -734,8 +749,14 @@ func run(args []string) error {
 	if systemMessage == "" {
 		systemMessage = defaultSystem
 	}
+	if resolved.GithubRepoDirectory != "" {
+		systemMessage += fmt.Sprintf("\n\nRepository directory: %s\nThis is the local clone of the project repository. You can read and modify files here.", resolved.GithubRepoDirectory)
+	}
+	if resolved.GithubRepoUrl != "" {
+		systemMessage += fmt.Sprintf("\nRepository URL: %s\nThis is the upstream GitHub repository.", resolved.GithubRepoUrl)
+	}
 
-	// Build sandbox config from resolved settings
+	// Build sandbox config from resolved settings (first occurrence)
 	sbCfg := sandboxConfig{
 		Image:    resolved.SandboxImage,
 		Network:  resolved.SandboxNetwork,
@@ -1529,8 +1550,14 @@ func continueCmd(args []string) error {
 	if systemMessage == "" {
 		systemMessage = defaultSystem
 	}
+	if resolved.GithubRepoDirectory != "" {
+		systemMessage += fmt.Sprintf("\n\nRepository directory: %s\nThis is the local clone of the project repository.", resolved.GithubRepoDirectory)
+	}
+	if resolved.GithubRepoUrl != "" {
+		systemMessage += fmt.Sprintf("\nRepository URL: %s\nThis is the upstream GitHub repository.", resolved.GithubRepoUrl)
+	}
 
-	// Sandbox (if enabled in config)
+	// Sandbox (if enabled in config) (second occurrence)
 	if resolved.Sandbox {
 		sbCfg := sandboxConfig{
 			Image:    resolved.SandboxImage,

cmd/odek/mcp.go

@@ -56,8 +56,14 @@ Flags:
 	if systemMessage == "" {
 		systemMessage = defaultSystem
 	}
+	if resolved.GithubRepoDirectory != "" {
+		systemMessage += fmt.Sprintf("\n\nRepository directory: %s\nThis is the local clone of the project repository. You can read and modify files here.", resolved.GithubRepoDirectory)
+	}
+	if resolved.GithubRepoUrl != "" {
+		systemMessage += fmt.Sprintf("\nRepository URL: %s\nThis is the upstream GitHub repository.", resolved.GithubRepoUrl)
+	}
 
-	// Build sandbox config from resolved settings
+	// Start agent loop (mcp)
 	sbCfg := sandboxConfig{
 		Image:    resolved.SandboxImage,
 		Network:  resolved.SandboxNetwork,

cmd/odek/repl.go

@@ -62,8 +62,14 @@ func replCmd(args []string) error {
 	if systemMessage == "" {
 		systemMessage = defaultSystem
 	}
+	if resolved.GithubRepoDirectory != "" {
+		systemMessage += fmt.Sprintf("\n\nRepository directory: %s\nThis is the local clone of the project repository. You can read and modify files here. When asked to update your own code, this is where the source lives.", resolved.GithubRepoDirectory)
+	}
+	if resolved.GithubRepoUrl != "" {
+		systemMessage += fmt.Sprintf("\nRepository URL: %s\nThis is the upstream GitHub repository.", resolved.GithubRepoUrl)
+	}
 
-	// Auto-apply sandbox if resuming a sandboxed session
+	// session resume
 	if sess != nil && sess.Sandbox && !resolved.Sandbox {
 		resolved.Sandbox = true
 		fmt.Fprintf(os.Stderr, "odek: session was sandboxed — enabling sandbox\n")

cmd/odek/serve.go

@@ -96,7 +96,14 @@ func serveCmd(args []string) error {
 	if systemMessage == "" {
 		systemMessage = defaultSystem
 	}
+	if resolved.GithubRepoDirectory != "" {
+		systemMessage += fmt.Sprintf("\n\nRepository directory: %s\nThis is the local clone of the project repository.", resolved.GithubRepoDirectory)
+	}
+	if resolved.GithubRepoUrl != "" {
+		systemMessage += fmt.Sprintf("\nRepository URL: %s\nThis is the upstream GitHub repository.", resolved.GithubRepoUrl)
+	}
 
+	// Build sandbox config from resolved settings (serve)
 	store, err := session.NewStore()
 	if err != nil {
 		return fmt.Errorf("session store: %w", err)

cmd/odek/telegram.go

@@ -118,8 +118,14 @@ func telegramCmd(args []string) error {
 	if systemMessage == "" {
 		systemMessage = defaultSystem
 	}
+	if resolved.GithubRepoDirectory != "" {
+		systemMessage += fmt.Sprintf("\n\nRepository directory: %s\nThis is the local clone of the project repository.", resolved.GithubRepoDirectory)
+	}
+	if resolved.GithubRepoUrl != "" {
+		systemMessage += fmt.Sprintf("\nRepository URL: %s\nThis is the upstream GitHub repository.", resolved.GithubRepoUrl)
+	}
 
-	// 10. Wire handler callbacks.
+	// Telegram-specific system prompt additions
 	//
 	// Important: OnTextMessage processes in a background goroutine so it doesn't
 	// block the main update processing loop. The TelegramApprover blocks waiting