initializ · initializ-mk · Mar 11, 2026 · Mar 11, 2026 · Mar 11, 2026 · Mar 11, 2026
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# Forge — Secure, Portable AI Agent Runtime
+# Forge — OpenClaw for Enterprise: A Secure, Portable AI Agent Runtime
 
 Build, run, and deploy AI agents from a single `SKILL.md` file.
 Secure by default. Runs anywhere — local, container, cloud, air-gapped.

diff --git a/docs/channels.md b/docs/channels.md
@@ -103,6 +103,16 @@ When the Slack adapter receives a message:
 
 This gives users visual feedback that their message is being processed, especially for long-running research queries.
 
+### Telegram Processing Indicators
+
+The Telegram adapter mirrors Slack's processing feedback:
+
+1. A typing indicator ("typing...") is sent immediately and refreshed every 4 seconds
+2. If the handler takes longer than 15 seconds, an interim message is posted: _"Working on it — I'll send the result when ready."_
+3. The typing indicator stops when the response is ready
+
+**Context isolation:** Each handler goroutine runs with an independent context (10-minute timeout), detached from the polling loop. This prevents in-flight tasks from being cancelled if the polling context is interrupted during server restarts or errors.
+
 ## Configuration
 
 ### Slack (`slack-config.yaml`)

diff --git a/docs/security/guardrails.md b/docs/security/guardrails.md
@@ -9,17 +9,32 @@ The guardrail engine checks inbound and outbound messages against configurable p
 | Guardrail | Direction | Description |
 |-----------|-----------|-------------|
 | `content_filter` | Inbound + Outbound | Blocks messages containing configured blocked words |
-| `no_pii` | Outbound | Detects email addresses, phone numbers, and SSNs via regex |
+| `no_pii` | Outbound | Detects email, phone, SSNs (with structural validation), and credit cards (with Luhn check) |
 | `jailbreak_protection` | Inbound | Detects common jailbreak phrases ("ignore previous instructions", etc.) |
 | `no_secrets` | Outbound | Detects API keys, tokens, and private keys (OpenAI, Anthropic, AWS, GitHub, Slack, Telegram, etc.) |
 
 ## Modes
 
 | Mode | Behavior |
 |------|----------|
-| `enforce` | Blocks violating messages, returns error to caller |
+| `enforce` | Blocks violating inbound messages; **redacts** outbound messages (see below) |
 | `warn` | Logs violation, allows message to pass |
 
+### Outbound Redaction
+
+Outbound messages (from the agent to the user) are always **redacted** rather than blocked, even in `enforce` mode. Blocking would discard a potentially useful agent response (e.g., code analysis) over a false positive from broad PII/secret patterns matching source code. Matched content is replaced with `[REDACTED]` and a warning is logged.
+
+### PII Validators
+
+To reduce false positives, PII patterns use structural validators beyond simple regex:
+
+| Pattern | Validator | What it checks |
+|---------|-----------|---------------|
+| SSN | `validateSSN` | Rejects area=000/666/900+, group=00, serial=0000, all-same digits, known test SSNs |
+| Credit card | `validateLuhn` | Luhn checksum validation, 13-19 digit length check |
+| Email | — | Regex only |
+| Phone | — | Regex only (area code 2-9, separators required) |
+
 ## Configuration
 
 Guardrails are defined in the policy scaffold, loaded from `policy-scaffold.json` or generated during `forge build`.

diff --git a/docs/skills.md b/docs/skills.md
@@ -163,7 +163,8 @@ forge skills list --tags kubernetes,incident-response
 
 | Skill | Icon | Category | Description | Scripts |
 |-------|------|----------|-------------|---------|
-| `github` | 🐙 | developer | Create issues, PRs, and query repositories | — (binary-backed) |
+| `github` | 🐙 | developer | Clone repos, create issues/PRs, and manage git workflows | `github-clone.sh`, `github-checkout.sh`, `github-commit.sh`, `github-push.sh`, `github-create-pr.sh`, `github-status.sh` |
+| `code-agent` | 🤖 | developer | Autonomous code generation, modification, and project scaffolding | — (builtin tools) |
 | `weather` | 🌤️ | utilities | Get weather data for a location | — (binary-backed) |
 | `tavily-search` | 🔍 | research | Search the web using Tavily AI search API | `tavily-search.sh` |
 | `tavily-research` | 🔬 | research | Deep multi-source research via Tavily API | `tavily-research.sh`, `tavily-research-poll.sh` |
@@ -356,6 +357,56 @@ This registers three tools:
 
 Requires: `jq`. Egress: `cdn.tailwindcss.com`, `esm.sh`.
 
+### GitHub Skill
+
+The `github` skill provides a complete git + GitHub workflow through script-backed tools:
+
+```bash
+forge skills add github
+```
+
+This registers eight tools:
+
+| Tool | Purpose |
+|------|---------|
+| `github_clone` | Clone a repository and create a feature branch |
+| `github_checkout` | Switch to or create a branch |
+| `github_status` | Show git status for a cloned project |
+| `github_commit` | Stage and commit changes |
+| `github_push` | Push a feature branch to the remote |
+| `github_create_pr` | Create a pull request |
+| `github_create_issue` | Create a GitHub issue |
+| `github_list_issues` | List open issues for a repository |
+
+**Workflow:** Clone → explore → edit → status → commit → push → create PR. The skill's system prompt enforces this sequence and prevents raw `git` commands via `cli_execute`.
+
+Requires: `gh`, `git`, `jq`. Optional: `GH_TOKEN`. Egress: `api.github.com`, `github.com`.
+
+### Code-Agent Skill
+
+The `code-agent` skill enables autonomous code generation and modification using [builtin code-agent tools](tools.md#code-agent-tools):
+
+```bash
+forge skills add code-agent
+```
+
+This registers eight tools:
+
+| Tool | Purpose |
+|------|---------|
+| `code_agent_scaffold` | Bootstrap a new project (Vite, Express, FastAPI, Go, Spring Boot, etc.) |
+| `code_agent_write` | Create or update files |
+| `code_agent_edit` | Surgical text replacement in existing files |
+| `code_agent_read` | Read a file or list directory contents |
+| `code_agent_run` | Install dependencies, start a server, open a browser |
+| `grep_search` | Search file contents by regex |
+| `glob_search` | Find files by name pattern |
+| `directory_tree` | Show project directory tree |
+
+The skill uses **denied tools** (`bash_execute`, `file_write`, `file_edit`, `file_patch`, `file_read`, `schedule_*`) to ensure the LLM uses the skill's own tool wrappers instead of raw builtins. All file operations are confined to the agent's working directory via `PathValidator`.
+
+Requires: `bash`, `jq`. Egress: `registry.npmjs.org`, `cdn.tailwindcss.com`, `pypi.org`, `files.pythonhosted.org`, `proxy.golang.org`, `sum.golang.org`, `storage.googleapis.com`, `repo.maven.apache.org`, `repo1.maven.org`.
+
 ## Skill Guardrails
 
 Skills can declare domain-specific guardrails in their `SKILL.md` frontmatter to enforce security policies at runtime. These guardrails operate at four interception points in the agent loop, preventing unauthorized commands, data exfiltration, capability enumeration, and binary name disclosure.

diff --git a/docs/tools.md b/docs/tools.md
@@ -36,6 +36,51 @@ Tools are capabilities that an LLM agent can invoke during execution. Forge prov
 
 Register all builtins with `builtins.RegisterAll(registry)`.
 
+## Code-Agent Tools
+
+When the `code-agent` skill is active, Forge registers additional tools for autonomous code generation and modification. These tools are **not** registered by default — they are conditionally added when the skill requires them.
+
+All code-agent tools use a `PathValidator` that confines resolved paths within the agent's working directory, preventing directory traversal attacks.
+
+| Tool | Description |
+|------|-------------|
+| `bash_execute` | Execute bash commands with pipes, redirection, and shell features |
+| `file_read` | Read file contents with optional line offset/limit, or list directory entries |
+| `file_write` | Create or overwrite files in the project directory |
+| `file_edit` | Edit files by exact string matching with unified diff output |
+| `file_patch` | Batch file operations (add, update, delete, move) in a single call |
+| `glob_search` | Find files by glob pattern (e.g., `**/*.go`), sorted by modification time |
+| `grep_search` | Search file contents with regex; uses `rg` if available, falls back to Go |
+| `directory_tree` | Display tree-formatted directory listing (default max depth: 3) |
+
+### Registration Groups
+
+Code-agent tools are registered in layered groups, allowing skills to request only the capabilities they need:
+
+| Group | Tools | Purpose |
+|-------|-------|---------|
+| `CodeAgentSearchTools` | `grep_search`, `glob_search`, `directory_tree` | Read-only exploration |
+| `CodeAgentReadTools` | `file_read` + search tools | Safe reading |
+| `CodeAgentWriteTools` | `file_write`, `file_edit`, `file_patch`, `bash_execute` | Modification + execution |
+| `CodeAgentTools` | All read + write tools | Full code-agent capability |
+
+### bash_execute Security
+
+| Layer | Detail |
+|-------|--------|
+| **Dangerous command denylist** | Blocks `rm -rf /`, `mkfs`, `dd`, fork bombs, and similar destructive patterns |
+| **sudo/su blocked** | Privilege escalation prefixes are rejected |
+| **Timeout** | Default 120s, configurable per invocation |
+| **Output cap** | Maximum 1MB output to prevent memory exhaustion |
+
+### Path Validation
+
+All file tools use `PathValidator` (from `pathutil.go`):
+
+- All resolved paths must stay within the configured `workDir`
+- Directory traversal via `..` is caught after symlink resolution
+- Standard directories are excluded from search: `.git`, `node_modules`, `vendor`, `__pycache__`, `.venv`, `dist`, `build`
+
 ## Adapter Tools
 
 | Adapter | Description |