From e97d2324b3b17c1c2c828e94e4daa52aab4c74e0 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Wed, 18 Nov 2026 17:34:51 +0100 Subject: [PATCH] docs(support): Document research commands and output formats --- README.md | 100 ++++++++++++++++++++++++++++++++++++++++---- docs/DEVELOPMENT.md | 24 +++++++++++ docs/OUTPUT.md | 87 ++++++++++++++++++++++++++++++++------ docs/TELEMETRY.md | 27 +++++++----- 4 files changed, 207 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 493303d..a8c544b 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ - Read APIs, inspect declarations, platform availability, conformances, and documented members. - Discover symbols, list technologies and search their documentation collections. +- Browse support articles, help guides, glossary definitions, agreements, and guidelines. - Use in scripts and agents to retrieve structured results, agent Markdown, and bundled Agent Skills. > [!NOTE] @@ -23,7 +24,7 @@ apple-docs --version For **Linux packages**, manual downloads, and checksums, see the [latest release notes](https://github.com/techprimate/apple-docs-cli/releases/latest). To build from source, see the [development guide](docs/DEVELOPMENT.md). -Fetching documentation requires internet access to Apple's documentation service. +Fetching documentation requires internet access to Apple's documentation services. ## Quick start @@ -72,9 +73,19 @@ Output reflects Apple's documentation and can change as Apple updates it. | `apple-docs types list --technology ` | List symbols linked directly from a technology's root page. | | `apple-docs types search --technology ` | Search symbols in a technology's documentation collections. | | `apple-docs types view --technology ` | Read a type's documentation. | +| `apple-docs support articles list` | Discover categorized support resources. | +| `apple-docs support guides list` | Discover help resources and topic groups. | +| `apple-docs support guides contents --name ` | Browse a guide's table of contents. | +| `apple-docs support glossary list` | List or filter glossary terms and definitions. | +| `apple-docs support glossary view --term ` | Read one glossary definition. | +| `apple-docs support terms list` | Discover agreements and guidelines. | +| `apple-docs support terms view --name ` | Read an entry's document resources and translations. | +| `apple-docs support view --path ` | Read a supported help or support HTML page. | | `apple-docs cache clean` | Clear cached documentation responses. | | `apple-docs agent skills list` | List bundled Agent Skills. | -| `apple-docs agent skills get apple-docs` | Print the bundled documentation skill. | +| `apple-docs agent skills get ` | Print a bundled research skill. | +| `apple-docs agent skills install ` | Install a selected bundled skill. | +| `apple-docs agent skills uninstall ` | Remove an unchanged managed skill. | Use `apple-docs --help` or append `--help` to a command for its arguments and options. @@ -132,14 +143,59 @@ apple-docs types view URLSession.AsyncBytes --technology Foundation apple-docs types view URLSession/AsyncBytes --technology Foundation ``` +### Support articles, guides, and glossary + +Discover categorized support resources and browse help guides: + +```bash +apple-docs support articles list +apple-docs support articles list --category membership +apple-docs support guides list +apple-docs support guides contents --name app-store-connect +``` + +Use category identifiers and guide names from returned resources or agent follow-up commands. Article catalogs contain resource links, not article bodies. Guide contents retain nested sections and page links. These commands are not full-text or exhaustive site search. + +Read a supported HTML page by its path relative to `developer.apple.com`: + +```bash +apple-docs support view --path support/fee-waiver +apple-docs support view --path help/app-store-connect/reference/app-information/screenshot-specifications +``` + +Paths must start with `help/` or `support/`. Do not pass full URLs, query strings, or fragments. The reader preserves available headings, lists, tables, code, links, images, breadcrumbs, and substantive notices. PDFs and unknown HTML layouts are unsupported. A link in a catalog does not guarantee that the CLI can read its contents. + +Find a glossary term, then read its definition: + +```bash +apple-docs support glossary list --query account +apple-docs support glossary view --term "Account Holder" +``` + +The query matches term names by case-insensitive substring, not definition text. Viewing a definition requires the exact displayed term, matched case-insensitively. + +### Agreements and guidelines + +```bash +apple-docs support terms list +apple-docs support terms list --category guidelines +apple-docs support terms view --name apple-developer-program-license-agreement +``` + +Copy category and entry identifiers from the catalog. An entry contains its description, document links, resource-specific translations, notices, and available update labels. It does not download the linked legal document or establish which agreement a user has accepted. Keep translations and notices associated with their original document resource. + +All support commands are stateless and accept `--agent` and `--json` independently. They do not take `--technology`. + ### Agent output -Use `--agent` on documentation commands for Markdown with explicit technology, paths, links, and safely quoted follow-up commands: +Use `--agent` on documentation and support commands for Markdown with explicit destinations, links, and safely quoted follow-up commands: ```bash apple-docs types view String --technology Swift --agent apple-docs types search Button --technology SwiftUI --agent apple-docs technologies list --agent +apple-docs support guides contents --name app-store-connect --agent +apple-docs support view --path support/fee-waiver --agent ``` Agent output uses the same normalized documentation content as human text. Follow-up commands are included only for destinations the CLI can represent safely. All commands remain one-shot, even when run in a terminal. @@ -148,7 +204,7 @@ Agent output uses the same normalized documentation content as human text. Follo ### JSON output -The documentation commands accept `--json` for normalized semantic output: +The DocC documentation commands accept `--json` for normalized semantic output: | Command | JSON output | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -157,7 +213,17 @@ The documentation commands accept `--json` for normalized semantic output: | `types search` | An object containing `technology`, a `types` array, and `coverage` with completeness and typed collection failures. | | `technologies list` | A sorted array of `name` and `identifier` objects. | -Add `--agent` to include `navigation` commands for supported destinations. Content blocks retain semantic types and links distinguish documentation, external, and unavailable targets. Availability includes `introducedAt`, `deprecatedAt`, `obsoletedAt`, `isBeta`, and `isUnavailable` when applicable. Inapplicable optional fields are omitted. +Support commands return objects tagged with `kind`, including catalogs, guide contents, glossary definitions, terms entries, and articles. For example: + +```bash +apple-docs support articles list --agent --json +apple-docs support glossary view --term "Account Holder" --json +apple-docs support view --path support/fee-waiver --agent --json +``` + +Support JSON has its own catalog and rich-content shapes, distinct from DocC pages. See [Output formats and JSON](docs/OUTPUT.md#support-json-result-shapes) for fields and examples. + +Add `--agent` to include `navigation` commands for supported destinations. DocC content blocks retain semantic types and links distinguish documentation, external, and unavailable targets. Availability includes `introducedAt`, `deprecatedAt`, `obsoletedAt`, `isBeta`, and `isUnavailable` when applicable. Inapplicable optional fields are omitted. ```bash apple-docs types view String --technology Swift --json @@ -171,7 +237,7 @@ For example, extract the documented title using [jq](https://jqlang.org/), insta apple-docs types view String --technology Swift --json | jq -r '.title' ``` -This is a breaking change: page JSON is normalized rather than raw DocC, and title extraction uses `.title` instead of `.metadata.title`. There is no raw-DocC export flag. Normalization does not preserve every upstream field, so missing normalized content is not evidence that Apple supplies no such information. JSON stdout contains only the result, with warnings and verbose diagnostics sent to stderr. +Page JSON is normalized rather than raw DocC. There is no raw-DocC export flag. Normalization does not preserve every upstream field, so missing normalized content is not evidence that Apple supplies no such information. JSON stdout contains only the result, with warnings and verbose diagnostics sent to stderr. See [Output formats and JSON](docs/OUTPUT.md) for the complete normalized JSON shapes, link targets, and follow-up-command limitations. @@ -185,7 +251,7 @@ apple-docs cache clean ## Agent Skills -The executable includes task-specific guidance for coding agents. Ask your agent to read the bundled skill when using `apple-docs` to look up APIs. The root help points agents to the catalog: +The executable includes task-specific research guidance for coding agents. List available skills and their descriptions, then read the relevant skill before researching: ```bash apple-docs agent skills list @@ -197,9 +263,27 @@ Print the bundled skill without installing files: apple-docs agent skills get apple-docs ``` +Preview and install all bundled skills: + +```bash +apple-docs agent skills install --all --dry-run +apple-docs agent skills install --all +``` + +The default destination is `~/.agents/skills`. Use `--project` for `.agents/skills` beneath the Git root, or beneath the current directory outside Git. Use `--dir ` for another `.agents` root. Installation does not configure individual agent tools, which must support this directory convention. + +To remove managed skills, preview first: + +```bash +apple-docs agent skills uninstall --all --dry-run +apple-docs agent skills uninstall --all --yes +``` + +`--force` replaces differing managed skill files during installation, never unmanaged files. Uninstall refuses to remove modified managed skills and preserves unrelated files. Bulk removal requires `--yes` unless previewing with `--dry-run`. Agents should obtain approval before installation or removal. + ## Telemetry -macOS builds include Sentry telemetry for errors, crashes, command traces, logs, and metrics. Command metadata can include the requested technology and type. Linux builds do not include the Sentry SDK. +macOS builds include Sentry telemetry for errors, crashes, command traces, logs, and metrics. API command metadata can include the requested technology and type. Support commands record their command name and JSON output mode, not lookup paths, filters, or terms. Linux builds do not include the Sentry SDK. See the [telemetry policy](docs/TELEMETRY.md) for details. Disable telemetry for a command: diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index b40ee31..165a5e6 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -48,6 +48,30 @@ pre-commit install | `make format` | Format Swift with `swift format` and JSON, YAML, Markdown, and TOML with dprint. | | `make help` | Show all development commands. | +## Focused verification + +Start with the tests for the behavior you changed. For support commands and their live Apple pages: + +```bash +make test TEST_ARGS="--filter SupportCommandTests --filter SupportRendererTests" +make test-integration INTEGRATION_FILTER=SupportCommandIntegrationTests +./dist/apple-docs support view --path support/fee-waiver --agent --json +``` + +The live suite exercises catalogs, guide contents, glossary definitions, terms resources, and supported HTML layouts. It requires internet access and runs against the release executable, not a mocked service. + +For bundled research skills, verify discovery, retrieval, and the existing installation behavior: + +```bash +make test TEST_ARGS="--filter BundledAgentSkillsTests --filter AgentSkillsCommandTests --filter AgentSkillsInstallationTests" +make build +./dist/apple-docs agent skills list +./dist/apple-docs agent skills get apple-docs +./dist/apple-docs agent skills install --all --dry-run --project +``` + +Use a dry run to inspect installation destinations without changing agent configuration. Follow the [repository instructions](../AGENTS.md) for source organization and skill bundling. Focused checks supplement the full verification commands below. + ## Linux workflows Container commands mount the source read-only and keep build products in Docker volumes, separate from the host build directory. The two test architectures use isolated volumes. Select one architecture or narrow the tests when needed: diff --git a/docs/OUTPUT.md b/docs/OUTPUT.md index 17f69d7..315c75e 100644 --- a/docs/OUTPUT.md +++ b/docs/OUTPUT.md @@ -11,7 +11,7 @@ Documentation commands select audience and format independently. Human text, age | `--agent` | Agent | Markdown | | `--agent --json` | Agent | JSON with navigation commands | -All commands print once and exit, including when stdin and stdout are terminals. There is no interactive browser or `--non-interactive` flag. Flag order does not matter. These output options belong to `types view`, `types list`, `types search`, and `technologies list`, not to cache or skill commands. +All commands print once and exit, including when stdin and stdout are terminals. There is no interactive browser or `--non-interactive` flag. Flag order does not matter. These output options belong to `types view`, `types list`, `types search`, `technologies list`, and every support catalog or content command, not to cache or skill commands. Successful output goes to stdout. Errors, partial-search warnings, and requested verbose diagnostics go to stderr. Unhandled command failures exit nonzero. JSON stdout contains only the structured result, without terminal escape sequences or progress messages. @@ -20,21 +20,26 @@ apple-docs types view String --technology Swift apple-docs types view String --technology Swift --agent apple-docs types view String --technology Swift --json apple-docs types view String --technology Swift --agent --json +apple-docs support view --path support/fee-waiver --agent --json ``` ## Human and agent content Human text uses section headings, declarations, availability tables, prose, and grouped references. Agent Markdown uses predictable headings, explicit technology and path information, and copyable follow-up commands. Agent output does not deliberately summarize or remove content to save tokens. +Support text also preserves available lists, code, tables, images, and notices. Agent Markdown escapes literal text and uses safe code and link delimiters. JSON retains table-cell spans and named anchors that need not have an identical text representation. + Parity means the representations share normalized content. It does not promise support for every upstream DocC field or identical fields in every output format. Missing normalized content is not evidence that Apple supplies no such content. -Agent navigation uses supported CLI commands, explicit technology arguments, `--agent`, and shell-quoted values. Technology roots use `types list`. Representable document paths use `types view`. External or unavailable targets have no CLI navigation command. +For DocC APIs, agent navigation uses supported CLI commands, explicit technology arguments, `--agent`, and shell-quoted values. Technology roots use `types list`. Representable document paths use `types view`. External or unavailable targets have no CLI navigation command. Named CLI input interprets dots as hierarchy separators and lowercases paths. Normalized documentation links preserve Apple's path spelling and punctuation. The presenter omits follow-up commands for paths that cannot round-trip through named input rather than fabricating a command. Dash-prefixed operands use the argument terminator (`--`). -## JSON result shapes +For support resources, agent navigation selects catalog, guide-contents, glossary, terms-entry, or document commands and quotes their identifiers. Follow-up commands are generated only for recognized destinations. Other links remain references, including PDFs and unsupported pages. A generated command still depends on the source page retaining a supported layout. + +## DocC JSON result shapes -There is no versioned envelope. Page and search output are objects. Symbol and technology catalogs are top-level arrays. +There is no versioned envelope. DocC page and search output are objects. Symbol and technology catalogs are top-level arrays. ### Pages @@ -86,20 +91,78 @@ No search matches is a successful result with an empty `types` array, not an err Completeness refers to the reachable curated collection graph, not an exhaustive index of every symbol. Partial results remain usable and also emit a warning to stderr. Unexpected failures abort the search. Human text reports no matches explicitly. Cancellation stops the search rather than returning partial results. -## Compatibility with older output +## Support JSON result shapes + +Every support result is an object with a `kind` discriminator. Catalogs retain their source hierarchy rather than flattening into DocC symbol arrays. + +| Command | `kind` | Payload fields | +| ------------------------- | ----------------- | ---------------------------------------------------------------------------------- | +| `support articles list` | `articlesCatalog` | `header`, `categories` | +| `support guides list` | `helpCatalog` | `header`, `featuredResources`, `topicsTitle`, `topics`, `glossary` | +| `support guides contents` | `guideContents` | `header`, `entries` | +| `support glossary list` | `glossary` | `header`, `entries` | +| `support glossary view` | `glossaryEntry` | `term`, `definition` | +| `support terms list` | `termsCatalog` | `header`, `categories` | +| `support terms view` | `termsEntry` | `id`, `title`, `description`, `resources` | +| `support view` | `article` | `url`, `title`, optional `context`, `breadcrumbs`, `content`, `related`, `notices` | + +A header contains `url`, `title`, and `introduction`. Page links contain `title` and `url`, not DocC `target` records. Described links contain a `link` and a `summary`. + +Agent JSON additionally contains a `navigation` array, which may be empty. Each navigation entry has `title`, `command`, and an optional `url`. Human JSON omits `navigation`. Glossary and terms-entry selectors can generate commands without a URL. + +### Catalog hierarchy and document resources + +- Article categories contain `id`, `title`, `summary`, and `links`. +- Help topics contain `title` and `groups`. Each group has `links` and an optional `title`. Featured resources and the glossary use described links. +- Guide entries contain `title`, an optional `link`, and recursively nested `children`. +- Glossary entries contain `term` and a `definition` array of support content blocks. +- Terms categories contain `id`, `title`, block-valued `introduction`, and `entries`. Each entry has `id`, `title`, inline-valued `description`, and `resources`. +- A terms resource has a `link` and an optional `translations` object. That object contains block-valued `notice`, optional `lastUpdatedLabel`, and a `translations` array of page links. Translation groups belong to their individual resource, not the entire catalog entry. + +Category filters use source identifiers. Glossary queries match term names, not definition text. Empty glossary matches return an empty `entries` array. Unknown category identifiers, missing terms, and unsupported layouts fail rather than returning an unrelated result. -The current output contracts differ from the earlier raw-DocC interface: +Terms output describes public document resources. It does not include the linked legal document text or establish account-specific acceptance. Supported HTML landing pages can expose notices without containing the agreement itself. PDFs and unknown layouts are not parsed. -- `--agent` emits Markdown rather than acting as an alias for `--json`. -- Use both `--agent --json` for structured agent output. -- `types view --json` emits normalized semantic content, not unchanged upstream DocC bytes. -- There is no replacement raw-DocC export flag. -- Search JSON uses an object rather than a top-level array. Read matches from `.types` and check `.coverage.isComplete`. +### Rich support content -For example, title extraction uses `.title`, not `.metadata.title`: +Support inline records have their own schema: + +| Inline `type` | Fields | +| ----------------------------------- | -------------------------------- | +| `text`, `code` | `text` | +| `emphasis`, `strong`, `superscript` | Recursive `content` inline array | +| `link` | Inline `label` array and `url` | +| `image` | `url`, `alt` | +| `anchor` | `name`, inline `content` | +| `lineBreak` | No additional fields | + +Support blocks retain ordered structure: + +| Block `type` | Fields | +| ------------- | ---------------------------------- | +| `paragraph` | Inline `content` | +| `heading` | `level`, `text`, optional `anchor` | +| `list` | `ordered`, `start`, `items` | +| `codeListing` | String `text`, optional `syntax` | +| `aside` | `style`, block `content` | +| `table` | `rows` | +| `image` | `url`, `alt`, inline `caption` | +| `separator` | No additional fields | + +Each list item is an array of blocks. Table rows contain `cells`; each cell has block-valued `content`, `isHeader`, `columnSpan`, and `rowSpan`. Inline images can appear inside links, paragraphs, lists, or table cells. + +Articles retain available canonical URLs, ordered breadcrumbs, related page links, and substantive footer notices. Breadcrumbs contain `title` and an optional `url`. Named anchors are represented by inline `anchor` records or heading `anchor` fields. Optional fields are omitted when absent; array fields remain arrays when empty. + +### Reading structured results + +Parse JSON with a tool such as [jq](https://jqlang.org/), installed separately: ```bash apple-docs types view String --technology Swift --json | jq -r '.title' +apple-docs support guides contents --name app-store-connect --json | jq -r '.entries[].title' +apple-docs support terms view --name apple-developer-program-license-agreement --json | jq -r '.resources[].link.url' ``` +JSON contains normalized semantic content, not original DocC bytes or raw HTML. There is no raw-document export flag, and a missing normalized field is not evidence that Apple supplies no such information. + See [Development](DEVELOPMENT.md) for verification commands and [Telemetry](TELEMETRY.md) for the separate diagnostic-upload policy. diff --git a/docs/TELEMETRY.md b/docs/TELEMETRY.md index 7c35538..a047352 100644 --- a/docs/TELEMETRY.md +++ b/docs/TELEMETRY.md @@ -1,6 +1,6 @@ # Telemetry -`apple-docs` uses telemetry to understand failures, improve reliability, and learn which parts of Apple documentation are useful. Telemetry is enabled by default and can be disabled by setting `TELEMETRY_DISABLED=true`. +macOS builds of `apple-docs` use Sentry telemetry to understand failures, improve reliability, and learn which parts of Apple documentation are useful. Linux builds use a no-op telemetry implementation. Telemetry is enabled by default on macOS and can be disabled by setting `TELEMETRY_DISABLED=true`. ## Principles @@ -25,18 +25,22 @@ Invalid commands, missing required arguments, invalid flags, and command-level v ### Command Context -Each leaf command starts a `console.command` transaction and opts in to a fixed set of fields. +Instrumented commands start a `console.command` transaction and opt in to a fixed set of fields. -| Command | Captured fields | -| ------------------- | ------------------------------------------------------------------ | -| `types view` | Command name, documentation type, technology, and JSON output mode | -| `types list` | Command name, technology, and JSON output mode | -| `types search` | Command name, technology, and JSON output mode | -| `technologies list` | Command name and JSON output mode | -| `agent skills list` | Command name | -| `agent skills get` | Command name | +| Command | Captured fields | +| -------------------------------------- | ------------------------------------------------------------------ | +| `types view` | Command name, documentation type, technology, and JSON output mode | +| `types list` | Command name, technology, and JSON output mode | +| `types search` | Command name, technology, and JSON output mode | +| `technologies list` | Command name and JSON output mode | +| `support` catalog and content commands | Command name and JSON output mode | +| `cache clean` | Command name | +| `agent skills list` | Command name | +| `agent skills get` | Command name | -Documentation type and technology values are captured because they identify public Apple documentation and are required to reproduce page-specific failures. Other positional values are excluded unless explicitly approved. +Documentation type and technology values are captured because they identify public Apple documentation and are required to reproduce page-specific failures. Support paths, guide names, category filters, glossary queries and terms, and agreement identifiers are not attached to command context. Agent Skill installation and removal do not start command transactions or attach skill names and installation paths as command context. + +Other positional values are excluded unless explicitly approved. ### Logs @@ -68,6 +72,7 @@ Metric names and attributes are allowlisted. Type and technology are the only va The CLI does not intentionally send: - Raw process arguments or type search queries. +- Support lookup paths, identifiers, category filters, or glossary queries and terms. - Environment variables. - User identity or account information. - IP addresses or geographic location.