docs: add GLOSSARY.md + docs/solutions/ archive#199
Merged
Conversation
Two artifacts inspired by cli-printing-press, designed to compound over time as institutional memory that future contributors (human and AI) can grep before rediscovering the same patterns. **docs/GLOSSARY.md** — canonical terms for jamf-cli's overlapping vocabulary: Pro vs Platform vs Classic; blueprint vs config profile; smart vs static group; scope vs target; MDM command vs declaration; ADE vs DEP; etc. Closes the "which 'profile' / 'group' / 'policy' do you mean?" ambiguity that costs a round-trip in every AI conversation. **docs/solutions/** — categorized markdown postmortems with YAML frontmatter (title, date, category, module, problem_type, severity, applies_when, tags). Five category subdirs match cli-printing-press: best-practices, conventions, design-patterns, logic-errors, security-issues. Two seed entries: - conventions/output-flag-matrix-2026-05-08.md — exercise -o json/yaml/csv, --quiet, --no-color, --out-file for every new command before declaring done. Captures the lessons from #194 (spinner+NO_COLOR) and #195 (version -v -o json). - design-patterns/cobra-annotations-as-policy-2026-05-11.md — prefer Cobra Annotations for per-command policy metadata (lint:keep-flag, future mcp:hidden, jamf:destructive) over comment magic, separate registries, or per-tool allowlists. Captures the design choice from #198. CLAUDE.md gets a "Read first" section pointing at both so future Claude sessions discover them at session start. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…f.com Validated the glossary against Jamf Product Documentation via Ask Jamf MCP. Several entries had errors from working off codebase signals + training-era knowledge rather than authoritative docs: - **Scope (biggest correction):** Scope in Jamf Pro is the *unified* concept comprising three sub-functions: targets, limitations, exclusions. Targets are *part of* scope, not a separate Platform-only concept. Limitations and exclusions weren't in the glossary at all — added, along with the rule "exclusions always override targets and limitations." - **Blueprint:** Originally described as "the Platform API's DDM container." Actually a Jamf Pro AND Jamf School feature, built on DDM, scoped to smart/static groups. Available in both products. Now also supports configuration-profile payloads alongside declarations. - **DDM:** Was framed as "Apple's newer pull-based config model." Per Apple/Jamf docs, DDM is an *additive* layer on top of MDM, not a replacement. Devices apply declarations proactively and report state via the *status channel*. Added the status channel as its own entry. - **PreStage enrollment:** Capitalization fix (capital S). Added the "settings sync with Apple every two minutes" detail. - **ADE / DEP:** Per Jamf School docs, "DEP" is *explicitly* the formerly- used name. Tightened wording. Added Account-driven Device Enrollment as the macOS 14+ alternative to PreStage. - **Compliance Benchmarks:** Built on the macOS Security Compliance Project (mSCP) framework — added context. The UI uses "benchmark templates" + "rules" + "ODVs"; "baseline" is the Platform-API/CLI term and creates a naming gap. Now documented as such instead of presented as a single layer. - **Extension Attributes:** Added the auto-generated-per-benchmark pattern (`[Benchmark Name] - Failed Result List`). Added a Sources section pointing at the learn.jamf.com docs consulted and calling out that this is a point-in-time capture that should be updated as product renames happen (DEP → ADE, Azure ID → Microsoft Entra ID, etc.). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
neilmartin83
approved these changes
May 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two docs-only artifacts inspired by cli-printing-press, designed to compound over time as searchable institutional memory.
docs/GLOSSARY.md— canonical terms for jamf-cli's overlapping vocabulary (Pro vs Platform vs Classic, blueprint vs config profile, smart vs static group, scope vs target, MDM command vs declaration, ADE vs DEP).docs/solutions/— categorized postmortems and design-pattern docs with YAML frontmatter (title,date,category,module,problem_type,severity,applies_when,tags). Five category subdirs matching cli-printing-press:best-practices/,conventions/,design-patterns/,logic-errors/,security-issues/. Two seed entries.CLAUDE.md— adds a "Read first" section so future Claude Code sessions discover both at session start.Why
Two pain points this fixes:
Terminology round-trips. Every AI conversation has to relearn that "blueprint" means Platform/DDM, not Pro mobileconfig — and that "scope" (Pro) and "target" (Platform) are different fields with different APIs. The glossary closes that loop once.
Repeated rediscovery. PRs fix(spinner): suppress loading spinner under NO_COLOR / --no-color #194 (spinner+NO_COLOR) and fix(version): honour -o json/yaml and split classic spec section #195 (
version -vignoring-o json) were both follow-up fixes for patterns that should have been caught the first time. The convention seed captures the rule so the next new command exercises the full output/flag matrix before merge.Seed entries
conventions/output-flag-matrix-2026-05-08.md— "Every new command must honor the global output/flag matrix." Distills the lessons from fix(spinner): suppress loading spinner under NO_COLOR / --no-color #194 and fix(version): honour -o json/yaml and split classic spec section #195 into a checklist plus four specific rules (ANSI consultsnoColor; verbose paths route through the formatter; marshal structs not prose; test what you ship).design-patterns/cobra-annotations-as-policy-2026-05-11.md— "Cobra annotations as policy contract for cross-cutting concerns." Documents the namespace conventions (lint:*,mcp:*,jamf:*) introduced by feat(lint): add dead-code lint for flags and unexported helpers #198'slint:keep-flagand explains why annotations beat comment magic, separate registries, and per-tool allowlists.Test plan
go build ./...— clean (docs-only change, but verified anyway)go test ./...— full suite greenmake lint— 0 issuesdocs/solutions/README.mdFuture seed entries
Worth adding (separate PRs, when motivated):
logic-errors/device-platform-nil-deref-2026-05-07.md— from fix(device): guard nil scope/deploymentState/target in platform sections #185best-practices/output-projection-flags.md— from the--compact/--selectwork in feat(output): add --compact flag for token-efficient agent output #189/feat(output): add --select flag for multi-field projection #190conventions/anti-reimplementation.md— when we add the lint for it (deferred from the tier-2 ranking)🤖 Generated with Claude Code