feat(agent): add global and repo-local agent integrations

README.md

@@ -41,6 +41,15 @@ tscli get --help
 tscli create key --help
 ```
 
+Initialize AI agent guidance and prompt surfaces globally by default, or pass `--dir .` for a repo-local install:
+
+```bash
+tscli agent init
+tscli agent update
+tscli agent init --dir .
+tscli agent update --dir .
+```
+
 ## ✨ Highlights
 
 | Area                     | What you can do                                                                                             |
@@ -122,6 +131,7 @@ The primary docs live in the in-repo Docsify site under `docs/`.
 Most useful pages:
 
 - `docs/getting-started.md`: install, first command, and flags
+- `docs/agents.md`: global and repo-local AI agent integrations plus refresh workflow
 - `docs/configuration.md`: config keys, profiles, and precedence
 - `docs/authentication.md`: API-key auth methods and security guidance
 - `docs/command-reference.md`: generated command reference and workflow

cmd/tscli/agent/cli.go

@@ -0,0 +1,19 @@
+package agent
+
+import (
+	agentinit "github.com/jaxxstorm/tscli/cmd/tscli/agent/init"
+	agentupdate "github.com/jaxxstorm/tscli/cmd/tscli/agent/update"
+	"github.com/spf13/cobra"
+)
+
+func Command(root *cobra.Command) *cobra.Command {
+	command := &cobra.Command{
+		Use:   "agent",
+		Short: "Manage AI agent integrations for tscli",
+		Long:  "Generate and refresh tscli-backed AI agent instructions, skills, prompts, and commands for either a repo-local checkout or global user-level tooling.",
+	}
+
+	command.AddCommand(agentinit.Command(root))
+	command.AddCommand(agentupdate.Command(root))
+	return command
+}

cmd/tscli/agent/init/cli.go

@@ -0,0 +1,47 @@
+package init
+
+import (
+	"fmt"
+	"strings"
+
+	pkgagent "github.com/jaxxstorm/tscli/pkg/agent"
+	"github.com/spf13/cobra"
+)
+
+func Command(root *cobra.Command) *cobra.Command {
+	var dir string
+	var tools []string
+	var force bool
+
+	cmd := &cobra.Command{
+		Use:   "init",
+		Short: "Initialize AI agent integrations for tscli",
+		Long:  "Generate tscli-backed AI agent instructions, command catalogs, and native prompt, skill, or command surfaces for supported tools.",
+		RunE: func(_ *cobra.Command, _ []string) error {
+			result, err := pkgagent.Init(root, pkgagent.InstallOptions{
+				RootDir: dir,
+				Tools:   tools,
+				Force:   force,
+			})
+			if err != nil {
+				return err
+			}
+
+			fmt.Printf("tscli agent integrations initialized (%s) in %s\n", result.InstallScope, result.RootDir)
+			fmt.Printf("tools: %s\n", strings.Join(result.Tools, ", "))
+			fmt.Printf("indexed leaf commands: %d\n", result.CommandCount)
+			fmt.Printf("manifest: %s\n", result.ManifestPath)
+			if result.InstallScope == pkgagent.ScopeLocal {
+				fmt.Printf("refresh with: tscli agent update --dir %s\n", result.RootDir)
+			} else {
+				fmt.Printf("refresh with: tscli agent update\n")
+			}
+			return nil
+		},
+	}
+
+	cmd.Flags().StringVar(&dir, "dir", "", "Optional repository root for a repo-local install; omit to install global user-level integrations")
+	cmd.Flags().StringSliceVar(&tools, "tool", nil, fmt.Sprintf("Tool integrations to install (supported: %s; availability depends on global vs local install target)", strings.Join(pkgagent.SupportedTools(), ", ")))
+	cmd.Flags().BoolVar(&force, "force", false, "Overwrite unmanaged files at generated target paths")
+	return cmd
+}

cmd/tscli/agent/update/cli.go

@@ -0,0 +1,39 @@
+package update
+
+import (
+	"fmt"
+	"strings"
+
+	pkgagent "github.com/jaxxstorm/tscli/pkg/agent"
+	"github.com/spf13/cobra"
+)
+
+func Command(root *cobra.Command) *cobra.Command {
+	var dir string
+	var force bool
+
+	cmd := &cobra.Command{
+		Use:   "update",
+		Short: "Refresh AI agent integrations for tscli",
+		Long:  "Refresh the generated tscli agent bundle using the tool selection recorded in the target manifest. Without --dir, update refreshes the global user-level install.",
+		RunE: func(_ *cobra.Command, _ []string) error {
+			result, err := pkgagent.Update(root, pkgagent.UpdateOptions{
+				RootDir: dir,
+				Force:   force,
+			})
+			if err != nil {
+				return err
+			}
+
+			fmt.Printf("tscli agent integrations updated (%s) in %s\n", result.InstallScope, result.RootDir)
+			fmt.Printf("tools: %s\n", strings.Join(result.Tools, ", "))
+			fmt.Printf("indexed leaf commands: %d\n", result.CommandCount)
+			fmt.Printf("manifest: %s\n", result.ManifestPath)
+			return nil
+		},
+	}
+
+	cmd.Flags().StringVar(&dir, "dir", "", "Optional repository root containing a repo-local tscli agent manifest; omit to update the global install")
+	cmd.Flags().BoolVar(&force, "force", false, "Overwrite unmanaged files at generated target paths")
+	return cmd
+}

coverage/coverage-gaps.json

@@ -2,8 +2,10 @@
   "openapi_operations": 85,
   "excluded_operations": [],
   "in_scope_operations": 85,
-  "manifest_commands": 89,
+  "manifest_commands": 91,
   "excluded_commands": [
+    "agent init",
+    "agent update",
     "config get",
     "config profiles delete",
     "config profiles list",

coverage/coverage-gaps.md

@@ -3,8 +3,8 @@
 - OpenAPI operations: `85`
 - Excluded operations: `0`
 - In-scope operations: `85`
-- Manifest commands: `89`
-- Excluded commands: `9`
+- Manifest commands: `91`
+- Excluded commands: `11`
 - Covered operations: `85`
 - Uncovered operations: `0`
 - Covered commands: `80`

coverage/exclusions.yaml

@@ -3,6 +3,8 @@
 operations: {}
 
 commands:
+  agent init: "Local agent bundle generation command; no Tailscale API call."
+  agent update: "Local agent bundle refresh command; no Tailscale API call."
   config get: "Local config lookup command; no Tailscale API call."
   config profiles delete: "Local profile management command; no Tailscale API call."
   config profiles list: "Local profile management command; no Tailscale API call."

docs/README.md

@@ -9,13 +9,15 @@ This docs site is the source of truth for setup, authentication, configuration,
 New users:
 
 - [Getting Started](getting-started.md)
+- [AI Agent Integrations](agents.md)
 - [Authentication](authentication.md)
 - [Configuration](configuration.md)
 
 
 Existing users:
 
 - [Command Reference](command-reference.md)
+- [AI Agent Integrations](agents.md)
 - [Configuration](configuration.md)
 
 Contributors:

docs/_sidebar.md

@@ -1,5 +1,6 @@
 - [Home](/)
 - [Getting Started](getting-started.md)
+- [AI Agents](agents.md)
 - [Command Reference](command-reference.md)
 - [Configuration](configuration.md)
 - [Authentication](authentication.md)

docs/agents.md

@@ -0,0 +1,77 @@
+# AI Agent Integrations
+
+`tscli agent init` bootstraps `tscli`-aware instructions, skills, prompts, and commands so AI agents can use `tscli` directly instead of ad hoc API calls.
+
+## What it generates
+
+The command writes a versioned bundle into either your user-level config directories or a target repository.
+
+Global install surfaces:
+
+- `.config/tscli/agent/manifest.yaml`: versioned manifest used by `tscli agent update`
+- `.config/tscli/agent/commands.md`: generated catalog of the current `tscli` leaf commands
+- `.codex/skills/tscli/SKILL.md`: Codex skill surface
+- `.claude/commands/tscli-inspect.md`: Claude Code read-only slash command
+- `.claude/commands/tscli-operate.md`: Claude Code mutation slash command
+- `.config/opencode/commands/tscli-inspect.md`: OpenCode read-only command
+- `.config/opencode/commands/tscli-operate.md`: OpenCode mutation command
+
+Repo-local install surfaces:
+
+- `AGENTS.md`: global instructions for agent-aware tools
+- `CLAUDE.md`: Claude Code project memory
+- `.tscli/agent/manifest.yaml`: versioned manifest used by `tscli agent update`
+- `.tscli/agent/commands.md`: generated catalog of the current `tscli` leaf commands
+- `.codex/skills/tscli/SKILL.md`: Codex skill surface
+- `.github/skills/tscli/SKILL.md`: GitHub Copilot skill surface
+- `.github/prompts/tscli-inspect.prompt.md`: GitHub Copilot read-only prompt
+- `.github/prompts/tscli-operate.prompt.md`: GitHub Copilot mutation prompt
+
+## Initialize
+
+Install global user-level integrations:
+
+```bash
+tscli agent init
+```
+
+Install repo-local integrations into another directory:
+
+```bash
+tscli agent init --dir /path/to/repo
+```
+
+Restrict generation to selected tool surfaces:
+
+```bash
+tscli agent init --dir /path/to/repo --tool codex --tool claude --tool opencode
+```
+
+Supported `--tool` values are `generic`, `codex`, `claude`, `opencode`, and `copilot`.
+
+Global installs support `codex`, `claude`, and `opencode`.
+
+Repo-local installs support `generic`, `codex`, `claude`, `opencode`, and `copilot`.
+
+## Update
+
+Refresh the global generated bundle after upgrading `tscli` or adding new commands:
+
+```bash
+tscli agent update
+```
+
+Refresh a repo-local bundle:
+
+```bash
+tscli agent update --dir /path/to/repo
+```
+
+`update` reads the scope-appropriate manifest to preserve the original tool selection and rewrite the managed files in place.
+
+## Operating model
+
+- Agents should prefer `tscli list ...`, `tscli get ...`, `tscli create ...`, `tscli set ...`, and `tscli delete ...` over raw API calls when a command exists.
+- The generated command catalog is derived from the live Cobra command tree, so it stays aligned with the CLI surface.
+- Global command surfaces are reusable user-level integrations; repo-local instruction files remain project-scoped.
+- If a generated target path already contains an unmanaged file, rerun with `--force` only if you intend to replace it.

docs/commands/README.md

@@ -13,6 +13,9 @@ make docs-generate
 ## Commands
 
 - [tscli](tscli.md)
+- [tscli agent](tscli_agent.md)
+- [tscli agent init](tscli_agent_init.md)
+- [tscli agent update](tscli_agent_update.md)
 - [tscli config](tscli_config.md)
 - [tscli config get](tscli_config_get.md)
 - [tscli config profiles](tscli_config_profiles.md)

docs/commands/_sidebar.md

@@ -1,6 +1,9 @@
 <!-- Code generated by `make docs-generate`; DO NOT EDIT. -->
 
 - [tscli](tscli.md)
+- [tscli agent](tscli_agent.md)
+- [tscli agent init](tscli_agent_init.md)
+- [tscli agent update](tscli_agent_update.md)
 - [tscli config](tscli_config.md)
 - [tscli config get](tscli_config_get.md)
 - [tscli config profiles](tscli_config_profiles.md)

docs/commands/tscli.md

@@ -20,6 +20,7 @@ A CLI tool for interacting with the Tailscale API.
 
 ### SEE ALSO
 
+* [tscli agent](tscli_agent.md)	 - Manage AI agent integrations for tscli
 * [tscli config](tscli_config.md)	 - Config commands
 * [tscli create](tscli_create.md)	 - Create commands
 * [tscli delete](tscli_delete.md)	 - Delete commands

docs/commands/tscli_agent.md

@@ -0,0 +1,31 @@
+<!-- Code generated by `make docs-generate`; DO NOT EDIT. -->
+
+## tscli agent
+
+Manage AI agent integrations for tscli
+
+### Synopsis
+
+Generate and refresh tscli-backed AI agent instructions, skills, prompts, and commands for either a repo-local checkout or global user-level tooling.
+
+### Options
+
+```
+  -h, --help   help for agent
+```
+
+### Options inherited from parent commands
+
+```
+  -k, --api-key string   Tailscale API key
+  -d, --debug            Dump HTTP requests/responses
+  -o, --output string    Output: [human json pretty yaml]
+  -n, --tailnet string   Tailscale tailnet (default "-")
+```
+
+### SEE ALSO
+
+* [tscli](tscli.md)	 - 
+* [tscli agent init](tscli_agent_init.md)	 - Initialize AI agent integrations for tscli
+* [tscli agent update](tscli_agent_update.md)	 - Refresh AI agent integrations for tscli
+

docs/commands/tscli_agent_init.md

@@ -0,0 +1,36 @@
+<!-- Code generated by `make docs-generate`; DO NOT EDIT. -->
+
+## tscli agent init
+
+Initialize AI agent integrations for tscli
+
+### Synopsis
+
+Generate tscli-backed AI agent instructions, command catalogs, and native prompt, skill, or command surfaces for supported tools.
+
+```
+tscli agent init [flags]
+```
+
+### Options
+
+```
+      --dir string     Optional repository root for a repo-local install; omit to install global user-level integrations
+      --force          Overwrite unmanaged files at generated target paths
+  -h, --help           help for init
+      --tool strings   Tool integrations to install (supported: generic, codex, claude, opencode, copilot; availability depends on global vs local install target)
+```
+
+### Options inherited from parent commands
+
+```
+  -k, --api-key string   Tailscale API key
+  -d, --debug            Dump HTTP requests/responses
+  -o, --output string    Output: [human json pretty yaml]
+  -n, --tailnet string   Tailscale tailnet (default "-")
+```
+
+### SEE ALSO
+
+* [tscli agent](tscli_agent.md)	 - Manage AI agent integrations for tscli
+

docs/commands/tscli_agent_update.md

@@ -0,0 +1,35 @@
+<!-- Code generated by `make docs-generate`; DO NOT EDIT. -->
+
+## tscli agent update
+
+Refresh AI agent integrations for tscli
+
+### Synopsis
+
+Refresh the generated tscli agent bundle using the tool selection recorded in the target manifest. Without --dir, update refreshes the global user-level install.
+
+```
+tscli agent update [flags]
+```
+
+### Options
+
+```
+      --dir string   Optional repository root containing a repo-local tscli agent manifest; omit to update the global install
+      --force        Overwrite unmanaged files at generated target paths
+  -h, --help         help for update
+```
+
+### Options inherited from parent commands
+
+```
+  -k, --api-key string   Tailscale API key
+  -d, --debug            Dump HTTP requests/responses
+  -o, --output string    Output: [human json pretty yaml]
+  -n, --tailnet string   Tailscale tailnet (default "-")
+```
+
+### SEE ALSO
+
+* [tscli agent](tscli_agent.md)	 - Manage AI agent integrations for tscli
+