ai.docs: add routine doc category for azure.ai.routines

Add a fifth doc category for the Foundry routine resource (the azure.ai.routines extension) alongside agent, connection, toolbox, and skill. Five topics under skills/routine/: overview (trigger+action model, lifecycle, CLI surface), triggers (timer / recurring / github_issue reference with cron, IANA time zones, and the 5-minute minimum interval rule), actions (agent-response vs agent-invoke reference with field matrices), manage (CRUD CLI for create/update/show/list/delete/enable/disable plus the YAML/JSON manifest format and the type-immutability rule), dispatch (manual --input dispatch + run history for debugging failed runs with error_type/error_message correlation).

Also: add azd ai routine to the embedded SKILL.md router and allowed-tools list; refresh README directory layout and example snippets; add CHANGELOG entry; add datetimes and repointed to cspell.yaml for the new content.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: therealjohn

cli/azd/extensions/azure.ai.docs/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 ### Added
 
+* `azd ai doc routine` command group with topics for the Foundry routine
+  resource (`overview`, `triggers`, `actions`, `manage`, `dispatch`).
+  Covers the `azure.ai.routines` extension lifecycle: the trigger +
+  action discriminated-union model, the trigger types reference (timer /
+  recurring / github_issue) including the 5-minute minimum cron interval
+  and IANA time-zone rules, the action types reference (agent-response /
+  agent-invoke) with field matrices, the imperative CLI (create /
+  update / show / list / delete / enable / disable) including the
+  manifest file format and the type-immutability rule, and the manual
+  dispatch + run-history flow for debugging.
 * `azd ai doc skill` command group with topics for the Foundry skill
   resource (`overview`, `manage`, `share`, `consume`). Covers the
   `azure.ai.skills` extension lifecycle: the versioned skill model
@@ -20,6 +30,6 @@
   child copies the bundled `azd-ai-skill` coding-agent pack into the
   user's project (the existing `--target` / `--path` / `--force` /
   `--output` flag surface is unchanged). No backwards-compatible alias.
-* The embedded `SKILL.md` router now lists the Foundry skill resource
-  docs alongside agent / connection / toolbox docs and adds
-  `azd ai skill` to the `allowed-tools` list.
+* The embedded `SKILL.md` router now lists the Foundry skill and routine
+  resource docs alongside agent / connection / toolbox docs and adds
+  `azd ai skill` and `azd ai routine` to the `allowed-tools` list.

cli/azd/extensions/azure.ai.docs/README.md

@@ -28,6 +28,14 @@ azd ai doc skill manage
 azd ai doc skill share
 azd ai doc skill consume
 
+# List topics for Foundry routines (azure.ai.routines)
+azd ai doc routine
+azd ai doc routine overview
+azd ai doc routine triggers
+azd ai doc routine actions
+azd ai doc routine manage
+azd ai doc routine dispatch
+
 # Install the embedded azd-ai-skill coding-agent pack into the project
 azd ai doc install skill --target copilot
 ```
@@ -88,11 +96,18 @@ internal/cmd/
       manage.md
       share.md
       consume.md
+    routine/          <-- topics for azure.ai.routines (Foundry routine resource)
+      overview.md
+      triggers.md
+      actions.md
+      manage.md
+      dispatch.md
   doc_catalog.go      <-- docCategories table (one entry per skills/ subdir)
   doc_agent.go        <-- per-extension subcommand (one per category)
   doc_connection.go
   doc_toolbox.go
   doc_skill.go
+  doc_routine.go
 ```
 
 To add a new sibling:

cli/azd/extensions/azure.ai.docs/cspell.yaml

@@ -42,11 +42,14 @@ words:
   - parseable
   # Foundry-skills terms used in skill/* topic markdown bodies.
   # `agentskills` references the agentskills.io naming spec.
-  # `repoint` / `repoints` describe the metadata-only default-version
-  # update flow on Foundry skills (mirrors azure.ai.skills cspell.yaml).
+  # `repoint` / `repoints` / `repointed` describe the metadata-only
+  # default-version update flow on Foundry skills (mirrors azure.ai.skills cspell.yaml).
   - agentskills
   - repoint
   - repoints
+  - repointed
+  # Used in routine triggers.md when discussing one-shot timer firings.
+  - datetimes
 overrides:
   - filename: internal/cmd/doc_catalog.go
     words:

cli/azd/extensions/azure.ai.docs/internal/cmd/doc_catalog.go

@@ -201,6 +201,34 @@ var docCategories = []DocCategory{
 			"Print the hosted-agent consumption guide.": "azd ai doc skill consume",
 		},
 	},
+	{
+		Name:        "routine",
+		DisplayName: "Foundry routines (azure.ai.routines)",
+		// Foundry routines pair a trigger (timer / recurring / event)
+		// with an action (invoke an agent). Managed via the
+		// `azd ai routine` CLI (from the `azure.ai.routines`
+		// extension). This is how a deployed agent gets billed work
+		// that fires on its own (scheduled or event-driven), as
+		// opposed to the on-demand `azd ai agent invoke` path.
+		Short: "Manage Foundry routines -- trigger + action pairs that fire on a schedule or event and invoke an agent " +
+			"(azure.ai.routines).",
+		Preamble: []string{
+			"A routine pairs a trigger (timer, recurring schedule, or external event) with an action " +
+				"(invoke an agent). Foundry fires the routine on its own when the trigger matches, " +
+				"or you can fire it manually with `azd ai routine dispatch`. Each firing records a " +
+				"RoutineRun row visible via `routine run list`.",
+			"Use `azd ai doc routine <topic>` to print one topic's body in full. " +
+				"Start with `overview` for the mental model, then `manage` for the CLI.",
+		},
+		Examples: map[string]string{
+			"List topics for routines.":               "azd ai doc routine",
+			"Print the overview topic.":               "azd ai doc routine overview",
+			"Print the trigger-types reference.":      "azd ai doc routine triggers",
+			"Print the action-types reference.":       "azd ai doc routine actions",
+			"Print the management CLI reference.":     "azd ai doc routine manage",
+			"Print the dispatch + run-history guide.": "azd ai doc routine dispatch",
+		},
+	},
 }
 
 // init populates the Topics field of every DocCategory from the

cli/azd/extensions/azure.ai.docs/internal/cmd/doc_renderer.go

@@ -255,6 +255,8 @@ func categoryExtensionName(cat DocCategory) string {
 		return "azure.ai.agents"
 	case "skill":
 		return "azure.ai.skills"
+	case "routine":
+		return "azure.ai.routines"
 	default:
 		return fmt.Sprintf("azure.ai.%s", cat.Name)
 	}

cli/azd/extensions/azure.ai.docs/internal/cmd/doc_routine.go

@@ -0,0 +1,64 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+// doc_routine.go implements `azd ai doc routine [topic]` -- prints
+// embedded routine-friendly markdown from skills/routine/*.md. Mirrors
+// doc_agent.go / doc_connection.go / doc_toolbox.go / doc_skill.go; all
+// five share printCategoryTopic and the embedded skillsFS in
+// doc_agent.go (via the //go:embed skills/*/*.md glob).
+//
+// These are docs for the Foundry Routine resource (trigger + action
+// pairs that fire on a schedule, a one-shot timer, or an external
+// event such as a GitHub issue, and invoke an agent on the project).
+// Managed via `azd ai routine` from the azure.ai.routines extension.
+//
+// Add a new topic by dropping a markdown file with front-matter into
+// skills/routine/; the catalog loader picks it up automatically.
+
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+// newRoutineCommand returns `azd ai doc routine [topic]`. When invoked
+// with no positional arg, prints the routine topic list. When invoked
+// with a positional topic name, prints that topic body.
+//
+// Acts as a single entry point an agent uses to load just the slice of
+// Foundry routine docs it needs to drive the `azd ai routine` CLI and
+// to author a routine manifest (trigger + action) for a deployed agent.
+func newRoutineCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "routine [topic]",
+		Short: "Print agent-friendly documentation for Foundry routines.",
+		// Long is intentionally empty: the styled Description function
+		// passed via helpformat.Install in root.go drives the --help
+		// preamble (the same string the RunE prints below for direct
+		// invocation). cmd.Example is also intentionally empty so
+		// helpformat.Install's cmd.Example auto-migration does not
+		// produce a duplicate Examples block alongside the Footer one
+		// we wire in root.go.
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if len(args) == 0 {
+				cat := FindCategory("routine")
+				if cat == nil {
+					return fmt.Errorf("doc catalog: routine category not registered")
+				}
+				out := cmd.OutOrStdout()
+				if _, err := fmt.Fprint(out, renderCatalogBody(*cat)); err != nil {
+					return err
+				}
+				if _, err := fmt.Fprint(out, renderCatalogExamples(*cat)); err != nil {
+					return err
+				}
+				return nil
+			}
+			return printCategoryTopic(cmd.OutOrStdout(), "routine", args[0])
+		},
+	}
+	return cmd
+}

cli/azd/extensions/azure.ai.docs/internal/cmd/help_styling_test.go

@@ -64,10 +64,10 @@ func TestDocRootHelp_StyledSections(t *testing.T) {
 		"third catalog example title missing")
 
 	// Cobra's Available Commands listing should include the visible
-	// leaves (agent, connection, toolbox, skill, install, version;
-	// metadata is reserved by the SDK and may appear as well -- not
-	// asserted).
-	for _, name := range []string{"agent", "connection", "toolbox", "skill", "install", "version"} {
+	// leaves (agent, connection, toolbox, skill, routine, install,
+	// version; metadata is reserved by the SDK and may appear as well
+	// -- not asserted).
+	for _, name := range []string{"agent", "connection", "toolbox", "skill", "routine", "install", "version"} {
 		assert.True(t, strings.Contains(out, name),
 			"Cobra subcommand list missing %q", name)
 	}

cli/azd/extensions/azure.ai.docs/internal/cmd/root.go

@@ -40,6 +40,7 @@ func NewRootCommand() *cobra.Command {
 	rootCmd.AddCommand(newConnectionCommand())
 	rootCmd.AddCommand(newToolboxCommand())
 	rootCmd.AddCommand(newSkillCommand())
+	rootCmd.AddCommand(newRoutineCommand())
 	rootCmd.AddCommand(newInstallCommand(extCtx))
 	rootCmd.AddCommand(newVersionCommand(&extCtx.OutputFormat))
 	rootCmd.AddCommand(newMetadataCommand(rootCmd))
@@ -105,6 +106,19 @@ func NewRootCommand() *cobra.Command {
 		}
 	}
 
+	// Same wiring for the routine category command. Mirrors the agent /
+	// connection / toolbox / skill blocks above. doc_routine.go stays
+	// cobra-only.
+	if routineCmd := findChild(rootCmd, "routine"); routineCmd != nil {
+		if cat := FindCategory("routine"); cat != nil {
+			c := *cat
+			helpformat.Install(routineCmd, helpformat.Options{
+				Description: func(*cobra.Command) string { return renderCatalogBody(c) },
+				Footer:      func(*cobra.Command) string { return renderCatalogExamples(c) },
+			})
+		}
+	}
+
 	// Walk the rest of the tree (skills, version, metadata) and apply
 	// default styling. InstallAll skips already-Installed commands so
 	// root and agent (above) keep their custom Description/Footer.

cli/azd/extensions/azure.ai.docs/internal/cmd/root_test.go

@@ -26,6 +26,8 @@ func TestNewRootCommand_HasAgentSubcommand(t *testing.T) {
 		"azd ai doc must expose the toolbox subgroup")
 	assert.Contains(t, names, "skill",
 		"azd ai doc must expose the skill subgroup (Foundry skill resource docs)")
+	assert.Contains(t, names, "routine",
+		"azd ai doc must expose the routine subgroup (Foundry routine resource docs)")
 	assert.Contains(t, names, "install",
 		"azd ai doc must expose the install subgroup (embedded skill-pack installer)")
 }
@@ -87,6 +89,26 @@ func TestSkillsFS_HasAllSkillTopics(t *testing.T) {
 	}, got)
 }
 
+func TestSkillsFS_HasAllRoutineTopics(t *testing.T) {
+	// Pins the topic set for the Foundry routine resource docs (the
+	// azure.ai.routines extension). A future drop or rename is a
+	// deliberate test update -- topic names are the wire contract
+	// callers rely on (`azd ai doc routine <topic>`).
+	topics, err := loadCategoryTopics("routine")
+	require.NoError(t, err)
+	var got []string
+	for _, top := range topics {
+		got = append(got, top.Name)
+	}
+	assert.ElementsMatch(t, []string{
+		"overview",
+		"triggers",
+		"actions",
+		"manage",
+		"dispatch",
+	}, got)
+}
+
 func TestPrintCategoryTopic_KnownTopicEmitsBody(t *testing.T) {
 	var buf bytes.Buffer
 	require.NoError(t, printCategoryTopic(&buf, "agent", "initialize"))

cli/azd/extensions/azure.ai.docs/internal/cmd/skills/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: azd-ai-skill
 description: Set up, scaffold, configure, deploy, evaluate, and operate AI agents on Microsoft Foundry using the Azure Developer CLI (azd) and the azure.ai.agents extension. USE FOR azd ai agent, azd ai toolbox, foundry agent, agent.yaml, azure.yaml service config, hosted agent, deploying agents to Azure, running an agent locally, evaluating an agent, optimizing an agent, adding a tool to an agent, web search, code interpreter, file search, function tool, MCP server, OpenAPI tool, A2A peer agent, Azure AI Search RAG, Bing grounding, Bing Custom Search, toolbox, toolbox version, toolbox connection, connection, RemoteTool, CognitiveSearch, RemoteA2A, GroundingWithCustomSearch, OAuth2, UserEntraToken, AgenticIdentity, ProjectManagedIdentity, ApiKey, CustomKeys, model deployment, Foundry project endpoint. DO NOT USE FOR generic Azure CLI tasks unrelated to Foundry, or LLM application code that does not deploy to a Foundry hosted agent.
-allowed-tools: ["azd", "azd ai agent", "azd ai project", "azd ai toolbox", "azd ai connection", "azd ai skill", "azd ai doc", "azd version", "azd extension list", "azd auth login", "azd config get defaults", "azd env get-values"]
+allowed-tools: ["azd", "azd ai agent", "azd ai project", "azd ai toolbox", "azd ai connection", "azd ai skill", "azd ai routine", "azd ai doc", "azd version", "azd extension list", "azd auth login", "azd config get defaults", "azd env get-values"]
 ---
 # AZD AI skill
 
@@ -98,6 +98,22 @@ azd ai doc skill <topic>
 | Cross-team / cross-project sharing via download              | `share`       |
 | Wire downloaded SKILL.md into a Hosted agent + redeploy flow | `consume`     |
 
+## Topics: routines
+
+For managing **Foundry routines** -- trigger + action pairs that fire on a schedule, a one-shot timer, or an external event and invoke a deployed agent (the `azure.ai.routines` extension; `azd ai routine <verb>`). Routines are how a deployed agent gets billed work that fires on its own, as opposed to the on-demand `azd ai agent invoke` path:
+
+```bash
+azd ai doc routine <topic>
+```
+
+| Want to ...                                                  | Topic         |
+| ------------------------------------------------------------ | ------------- |
+| Mental model + trigger+action lifecycle + `azd ai routine` CLI surface | `overview`    |
+| Trigger types reference (timer / recurring / github_issue)   | `triggers`    |
+| Action types reference (agent-response / agent-invoke)       | `actions`     |
+| CLI reference (create / update / show / list / delete / enable / disable + manifest format) | `manage`      |
+| Manual dispatch + run history + debugging a failed run       | `dispatch`    |
+
 ## Resolving subscription, location, project ID
 
 `azd ai project show --output json` only returns the **Foundry project endpoint** (plus its resolution source) -- it does NOT return subscription, tenant, location, or resource group. For those, try in order: