@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/claude-code/ux-onboarding-copy/skill.yaml

@@ -0,0 +1,35 @@
+name: ux-onboarding-copy
+version: "1.0.0"
+description: Onboarding copy — progressive disclosure, value-first framing, reducing anxiety, and welcome flows that convert sign-ups into active users
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-microcopy-principles
+  - ux-voice-tone
+  - ux-writing-for-scanning
+  - ux-empty-states
+stack_signals: []
+keywords:
+  - onboarding
+  - welcome-flow
+  - first-run
+  - progressive-disclosure
+  - activation
+  - setup-wizard
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/ux-permission-access-copy/SKILL.md

@@ -0,0 +1,150 @@
+# Permission and Access Copy
+
+> Permission and access copy — role-based messaging, upgrade prompts, gating copy, "you don't have access" patterns
+
+## When to Use
+
+- Writing "permission denied" states for role-based access control (admin, editor, viewer)
+- Designing upgrade prompts and freemium feature gates
+- Building "request access" flows and access-pending states
+- Creating tooltips and inline copy for disabled UI elements
+- Composing contact-your-admin messaging for managed workspaces
+- Designing paywall interstitials and plan comparison nudges
+- NOT for: authentication errors like "Invalid password" or "Session expired" (use ux-error-messages)
+- NOT for: security warnings about suspicious activity or account lockouts
+- NOT for: general error states unrelated to access or entitlement
+
+## Instructions
+
+1. **Explain what the user cannot do AND who can do it.** A permission denied message that only says "You don't have permission" leaves the user with no path forward. Always name the role or person who can perform the action: "Only workspace admins can manage billing. Contact your admin to update the payment method." Linear names the specific permission level: "Only members with the Editor role can create cycles. Ask your workspace owner to update your role." GitHub's organization permission message names exactly which setting is restricted and links to the org settings page for administrators. The pattern is: what is blocked + who can unblock it + how to reach them. Omitting any of the three components forces the user to investigate on their own, which typically results in a support ticket rather than a self-served resolution.
+
+2. **Distinguish permission denied from feature unavailable -- the cause changes the copy.** A viewer who clicks "Edit" on a Figma file needs different copy than a free-tier user who clicks a Pro-only feature. Permission denied means the user has the product but lacks the role: "You have view-only access. Ask the file owner to give you edit access." Feature unavailable means the feature is behind a plan gate: "Version history is available on Professional and Organization plans." Conflating these causes the user to contact their admin when they actually need to upgrade, or to attempt an upgrade when they simply need a different role assigned to their account. Write the two message types using visually and textually distinct patterns so users can distinguish them at a glance without reading the full message.
+
+3. **Upgrade prompts show value before asking for money.** The moment a user hits a feature gate is high intent -- they already want the feature. Use that moment to show what they get, not what they must pay. Slack's upgrade prompt for message history says "Access all your message history -- messages before your current limit are already saved." The feature exists; the gate is temporary. Lead with the benefit: "Analyze trends across all time with Pro Analytics" rather than "Upgrade to Pro ($12/mo) to use this feature." Price comes after value is established -- leading with price anchors the user's thinking on cost rather than on the value that justifies the cost. Conversion rates on feature gates improve measurably when value is named before price.
+
+4. **Never blame or shame the user for lacking access.** Copy like "You don't have access to this feature" places the problem with the user. The product is placing a restriction; the product should own that framing. Prefer "This feature is available to Pro users" over "You can't use this feature." Figma's viewer restrictions say "You're viewing this file -- ask the owner for editor access" not "You don't have permission to edit." The difference is subtle but the user experience of being told you cannot do something versus being shown a path to unlock it is measurable in support ticket volume and user satisfaction scores. Avoid second-person "you" constructions that read as accusatory: "You don't have," "You can't," "You are not."
+
+5. **Provide a clear resolution path with a single primary action.** Every permission or access state must answer "what do I do now?" with a specific, tappable next step -- not a paragraph of explanation. The options are: (a) "Request access" button that triggers a real workflow, (b) contact info for the admin ("Email team@company.com"), (c) direct link to the upgrade page, or (d) a clear instruction to ask someone specific. GitHub's private repository 404 shows a "Request access" button that sends a notification to the repository admin. Notion shows "Ask for access" with a single click that notifies the workspace owner. Never present two equally weighted CTAs on the same permission denied state -- "Contact admin or upgrade" forces the user to diagnose their own situation instead of being routed to the correct resolution.
+
+6. **For freemium gates, show what the user is missing -- not a wall.** A lock icon with no explanation is the worst pattern. The user should be able to see enough of the gated feature to understand its value. Stripe shows anonymized chart data behind a blur on free-plan analytics: "Upgrade to see the full breakdown." Linear shows a grayed-out Cycles section with the label "Available on Plus and Pro plans -- explore Cycles." The goal is to create desire for the feature, not frustration at a closed door. Show the feature's shape; hide only the data. Features shown behind a preview gate convert at higher rates than features shown as a blank lock screen because desire requires understanding, and understanding requires seeing at least the outline of what is possible.
+
+7. **Disabled UI elements need a tooltip explaining why, not just a visual state.** A grayed-out button with no tooltip creates confusion: is it disabled because of a permission, a plan limit, the current state, or a bug? Slack disables the "Create channel" button for non-admin workspaces and shows on hover: "Only workspace admins can create channels." GitHub disables branch deletion on protected branches and shows: "This branch is protected. Unprotect it to delete." The tooltip must name the specific reason -- not "Not available" but "Protected by branch rules" or "Requires admin role." A disabled element without a tooltip is indistinguishable from a broken element, and users who cannot tell the difference file support tickets and lose trust in product quality.
+
+## Details
+
+### Role-Based Messaging Patterns
+
+Permission copy must account for the full matrix of roles a product supports. The most common failure is writing only the admin-facing copy and leaving viewer and editor states generic. Map each role to its specific constraint and write targeted copy for each:
+
+| Role      | Blocked Action         | Copy Pattern                                               |
+| --------- | ---------------------- | ---------------------------------------------------------- |
+| Viewer    | Edit content           | "You're viewing this [page]. Ask [owner] for edit access." |
+| Editor    | Manage billing         | "Only admins can manage billing. Contact your admin."      |
+| Member    | Invite users           | "Workspace owners can invite new members."                 |
+| Free user | Access Pro feature     | "Available on Pro -- [benefit statement]."                 |
+| Guest     | Access private content | "This content is restricted to workspace members."         |
+
+Consistency across these states requires a decision about voice. Linear uses a consistent "Only [role] can [action]" pattern. Figma uses "You're [current state] -- ask [actor] for [target state]." Choose one pattern and apply it everywhere in the product. Document the chosen pattern in the design system's content guidelines so that future writers default to it.
+
+### Freemium Gate Anatomy
+
+A well-designed freemium gate has five components, each doing specific work:
+
+1. **Gate label** -- The minimum viable signal that this is a paid feature. "Pro" or a lock icon. Keep it small; do not make the gate the dominant visual element.
+2. **Feature preview** -- Enough of the feature to communicate value. Blurred data, anonymized examples, or a screenshot. Never a completely blank state.
+3. **Value headline** -- One sentence naming the user's benefit, not the product's feature. "See how your team's time is spent" not "Access the Time Tracking report."
+4. **Plan context** -- Which plan includes this feature. "Available on Pro and Business plans." Link to the plans page.
+5. **Primary CTA** -- A single action. "Upgrade to Pro" or "Start free trial." Not "Learn more" as the primary action -- that is an escape hatch, not a conversion path.
+
+### Review Checklist
+
+Use this checklist before shipping or reviewing any permission or access state:
+
+| Check             | Criteria                                          | Pass Condition                                                    |
+| ----------------- | ------------------------------------------------- | ----------------------------------------------------------------- |
+| Cause identified  | Message names whether the issue is role or plan   | "permission denied" and "feature gate" use distinct copy patterns |
+| Resolution path   | Single primary action provided                    | One CTA, not "contact admin or upgrade"                           |
+| Role named        | Blocked state names who can unblock               | "Only admins can..." or "Ask the file owner..."                   |
+| No blame language | Copy does not use "you can't" or "you don't have" | Reframe to product-owned restriction ("Available on Pro...")      |
+| Value-first       | Upgrade prompts state benefit before plan name    | Benefit sentence appears before price or plan name                |
+| Disabled tooltips | All disabled elements have hover tooltip          | No grayed-out element is left unexplained                         |
+| Feature preview   | Gated features show a visible preview             | No blank lock screens; at least a blurred or anonymized view      |
+| Admin surfacing   | Permission denied states surface who the admin is | Name or email of relevant admin shown, not just "your admin"      |
+
+### Anti-Patterns
+
+1. **The Mysterious Denial.** "You don't have permission to view this page." No explanation of what permission is needed, who grants it, or how to get it. The user is stranded at a dead end with no self-service recovery path. Before: "Access denied." After: "This project is visible to Acme Corp members only. Request access or sign in with your Acme Corp account." The after version names the scope of restriction (Acme Corp members), offers two resolution paths (request access, different sign-in), and treats the user as capable of taking action rather than someone who has been turned away at a door.
+
+2. **The Guilt Trip Upgrade.** Upgrade prompts that frame the gate as punishment for being on the wrong plan. "Upgrade to unlock this feature" with no value statement. Before: "This feature is locked. Upgrade now." After: "Track time across all projects automatically -- available on Pro. See what's included." The after version leads with the benefit ("track time"), names the plan ("Pro"), and offers a soft next step ("see what's included") rather than demanding immediate commitment. The "locked" metaphor is inherently adversarial; replace it with a preview-and-unlock framing that aligns the product's incentive (upgrading) with the user's goal (using the feature).
+
+3. **The Dead End.** Permission denied states with no next step. The user reads the message, understands they are blocked, and has nowhere to go in the product. Before: "You don't have access to team billing." After: "Only admins can view billing. Contact your workspace admin at admin@yourcompany.com or ask them to update your role in Settings > Members." The after version names the admin contact directly, provides a navigation path for the admin to take action, and gives the user two concrete next steps. When the admin's email is not knowable, show the workspace admin's name with a "send message" button to initiate the contact within the product.
+
+4. **The Silent Disable.** A UI element that appears grayed out with no explanation. The user does not know if the button is disabled because of their role, the current state, or a bug in the product -- so they cannot determine whether to contact support, contact their admin, or wait for a state change. Before: [grayed-out "Export" button with no tooltip]. After: [on hover] "Export is available to workspace admins. Ask your admin to run this export." Every disabled element needs a tooltip. Every tooltip needs a specific reason. "Not available" is not a specific reason -- it is a restatement of the visual state.
+
+### Real-World Examples
+
+**Linear team permission states.** Linear surfaces role-based restrictions inline and contextually. When a viewer tries to drag an issue to a different status, a tooltip appears immediately: "You have view-only access to this team. Contact your workspace owner to update your role." The key design choices: the message appears at the exact point of friction (not a separate error page), it names the role required, and it names the person to contact with a link to workspace settings. Linear also shows a persistent "View only" badge in the workspace header so users always know their access level without discovering it through failed actions -- this is the "visibility of system status" principle applied to permission states.
+
+**Slack Enterprise upgrade prompts.** Slack's Business+ upgrade prompts appear in context -- inside the feature the user wants, not in a separate billing page. The message history limit prompt shows: "You're viewing the last 90 days. With Business+, your entire message history is searchable -- your messages before this date are saved and waiting." The copy does three things: names what the user is missing (older messages), removes the fear that data is lost (they are saved), and frames the upgrade as unlocking something that exists rather than buying something new. This framing reduces upgrade anxiety and increases conversion by addressing the specific objection a user is most likely to have at the point of encountering the gate.
+
+**GitHub organization permissions.** GitHub's org permission pages are among the most information-dense permission UIs in the industry. When a non-admin tries to access an org setting, the page shows: "You must be an organization owner to access organization settings. Contact an owner to request access." The page then lists current org owners with their avatars and usernames -- so the user can immediately identify who to contact without leaving GitHub. The "request access" model eliminates the ambiguity of "who is my admin?" by surfacing the answer in the permission denial state itself. This pattern reduces support ticket volume by making the resolution path self-contained within the product.
+
+**Figma editor/viewer gating.** Figma's distinction between editor and viewer is foundational to its business model, and the copy reflects that clarity. A viewer sees: "You're viewing this file. To make edits, ask [Owner name] to give you editor access." The owner's name is surfaced directly in the copy -- personalized, not generic. The "Request edit access" button sends a notification with the viewer's comment. Figma also shows a persistent "Viewing" indicator in the top bar so the access state is never ambiguous. For free-plan viewers on Organization files, Figma shows a separate nudge: "Upgrade to edit files in this organization" -- correctly distinguishing plan-gating from role-gating, so the user knows whether to contact an admin or upgrade their own account.
+
+### Copy Formulas Quick Reference
+
+These are fill-in-the-blank templates for the most common permission and access copy patterns:
+
+- **Role-blocked action (Linear pattern):** `Only [role]s can [action]. Ask your [role] to [resolution].`
+- **Role-blocked action (Figma pattern):** `You're [current role] -- ask [actor] for [target access].`
+- **Feature gate headline:** `[User benefit statement] -- available on [Plan name].`
+- **Feature gate CTA:** `Upgrade to [Plan]` or `Start [N]-day free trial`
+- **Request access:** `Request access` (button that triggers admin notification)
+- **Disabled element tooltip:** `[Action] requires [role] access. Ask your [admin / owner] to [resolution].`
+- **Admin surfacing:** `Contact [Admin name] at [email] or ask them to update your role in [Settings > Members].`
+- **Access pending:** `Access requested. [Admin name] will be notified.`
+- **Plan context:** `Available on [Plan A] and [Plan B] plans. See what's included.`
+- **Viewing indicator:** `You're viewing this [file / project / workspace].`
+
+## Source
+
+- Babich, N. -- "UX Design for Empty States and Permission Screens," Adobe XD Blog (2019)
+- NNGroup -- "Visibility of System Status," https://www.nngroup.com/articles/visibility-system-status/
+- Figma -- Design System and permission UX documentation, https://help.figma.com/hc/en-us/articles/360039970673
+- Linear -- Changelog and permission model, https://linear.app/docs/roles-and-permissions
+- Spotify Design -- "Designing Access States," Spotify Design Blog (2021)
+- Podmajersky, T. -- _Strategic Writing for UX_ (2019), Chapter 7: Permissions and Paywall Copy
+
+## Process
+
+1. **Map the full permission matrix for the feature.** List every role the product supports, what each role can do, and what each role cannot do. Write copy for each blocked state explicitly -- do not reuse generic copy across roles. Confirm the permission matrix with the engineering team before writing copy, because permission logic is often more nuanced in implementation than in the product spec.
+
+2. **For each blocked state, define the resolution path.** Determine whether the fix is a role change (route to admin contact or settings link), a plan upgrade (route to billing or upgrade page), or a prerequisite workflow step (route to the prerequisite action). A permission denied state with the wrong resolution path is worse than one with no path, because it sends the user in the wrong direction and erodes trust.
+
+3. **Write the permission message using the pattern: [what is blocked] + [who can unblock it] + [how to reach them or take action].** Confirm that the "who can unblock it" element names a specific role or a specific person (surfaced from the product's data) rather than a generic "your admin." The more specific the resolution path, the higher the self-service resolution rate.
+
+4. **Write the freemium gate using the pattern: [feature preview] + [value headline] + [plan context] + [single CTA].** Review the value headline with a product manager or marketing writer to confirm it names a user outcome, not a product feature name. A/B test the gate copy if the product has sufficient traffic -- small copy changes on feature gates produce measurable conversion differences.
+
+5. **Audit all disabled UI elements for tooltip coverage.** Build a list of every disabled button, link, and interactive element in the product. For each, write a tooltip that names the specific reason for the disabled state (not "not available" but the specific role, state, or plan required). Implement tooltips on hover for desktop and on tap for mobile -- on mobile, a long-press tooltip is the standard pattern for explaining a disabled element.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Every permission denied state names the role required and provides a specific resolution path (contact admin, request access, upgrade), not just a denial message.
+- Upgrade prompts lead with a user benefit statement before mentioning plan name or price, and the benefit is stated in terms of user outcome, not feature name.
+- No disabled UI element is left without a tooltip explaining the specific reason for the disabled state -- "not available" is not an acceptable tooltip.
+- Permission denied and feature unavailable states use visually and textually distinct copy patterns that correctly identify the cause so users route to the right resolution.
+- Users can identify and take the next action (contact admin, request access, upgrade) without leaving the screen where the restriction appears -- no resolution requires navigating to documentation.
+- Role-based messages use a consistent voice pattern established in the design system's content guidelines and applied uniformly across all permission states in the product.
+
+## Multi-Tenant and Enterprise Considerations
+
+In enterprise and multi-tenant products, permission denied states must account for the possibility that the user does not know who their admin is. A message that says "Contact your admin" assumes the user has a named admin contact. In organizations where IT manages the workspace, the admin may be an internal IT helpdesk rather than a named colleague. Write permission messages that either surface the admin's name from product data (when available) or provide a fallback: "Contact your workspace administrator. If you don't know who that is, ask your IT department or check Settings > Members."
+
+SSO-enforced workspaces create a specific permission pattern where users may be locked out not because of a role but because of an authentication requirement. "You must sign in with your company SSO to access this workspace" is a permission-adjacent state that requires a different copy pattern: name the identity provider if known ("Sign in with Okta"), explain what will happen after SSO authentication ("You'll rejoin the workspace with your existing role"), and provide a fallback if SSO is not working ("Having trouble? Contact your IT team at it@company.com").
+
+Freemium gates in enterprise contexts often involve organizational plans where an individual contributor cannot upgrade without admin approval. In these cases, "Upgrade to Pro" is the wrong CTA for the IC -- the correct CTA is "Request upgrade" or "Ask your admin to upgrade the workspace plan." Detect the organizational plan context and show the correct path: individual self-serve upgrade when available, admin-request flow when required by the billing model.

package/dist/agents/skills/claude-code/ux-permission-access-copy/skill.yaml

@@ -0,0 +1,34 @@
+name: ux-permission-access-copy
+version: "1.0.0"
+description: Permission and access copy — role-based messaging, upgrade prompts, gating copy, "you don't have access" patterns
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-microcopy-principles
+  - ux-error-messages
+  - ux-plain-language
+stack_signals: []
+keywords:
+  - permissions
+  - access-control
+  - role-based
+  - upgrade-prompt
+  - gating
+  - paywall
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/ux-plain-language/SKILL.md

@@ -0,0 +1,157 @@
+# Plain Language for UI
+
+> Plain language for UI — reading level targeting, jargon elimination, sentence structure for scanning
+
+## When to Use
+
+- Writing any user-facing text in a consumer or prosumer product
+- Simplifying technical concepts for non-technical users in settings, onboarding, or help text
+- Reducing the reading level of existing UI text that tests above grade 10 on Flesch-Kincaid
+- Writing help text, tooltips, and inline descriptions that must be understood on first read
+- Creating onboarding copy that introduces complex features to new users
+- Reviewing UI text that generates support tickets because users misunderstand the language
+- Writing error messages that non-technical users must act on without assistance
+- NOT for: developer-facing API documentation where technical precision requires domain terminology
+- NOT for: internal tooling built exclusively for domain experts who share a specialized vocabulary
+
+## Instructions
+
+1. **Target a sixth-to-eighth grade reading level for consumer products.** The Flesch-Kincaid readability formula measures sentence length and syllable count. A sixth-grade reading level means average sentences of 12-15 words using common two-syllable words. This is not dumbing down -- it is optimizing for speed and comprehension. The Nielsen Norman Group found that even users with graduate degrees prefer content written at a lower reading level because it is faster to process. Use the Hemingway App or readability plugins to measure. Stripe's user-facing text consistently scores at grade 6-8 even when explaining complex payment concepts.
+
+2. **Replace jargon with common words.** Every domain has its jargon, and that jargon feels natural to the team that builds the product. It does not feel natural to the user. Maintain a substitution list and enforce it in code reviews:
+
+   | Jargon       | Plain alternative   |
+   | ------------ | ------------------- |
+   | utilize      | use                 |
+   | initialize   | start               |
+   | terminate    | end                 |
+   | authenticate | sign in             |
+   | configure    | set up              |
+   | deploy       | publish             |
+   | propagate    | spread / update     |
+   | deprecated   | no longer supported |
+   | payload      | data                |
+   | parameter    | setting / option    |
+   | execute      | run                 |
+   | instantiate  | create              |
+   | invoke       | call / use          |
+   | persist      | save                |
+   | iterate      | repeat / go through |
+   | synchronize  | sync / update       |
+   | enumerate    | list                |
+   | concatenate  | combine / join      |
+   | obfuscate    | hide                |
+   | remediate    | fix                 |
+
+   Google's Material Design guidelines explicitly state: "Avoid technical jargon unless it is widely understood by your target audience." Notion calls pages "pages" because that is what users call them. GitHub uses "fork" but defines it on first encounter: "Fork -- create your own copy of this repository."
+
+3. **One idea per sentence.** If a sentence contains a comma followed by a conjunction ("and," "but," "or"), it probably contains two ideas and should be split. "Your trial has expired and you need to upgrade to continue using premium features" becomes "Your trial has expired. Upgrade to keep premium features." The split improves scanning, comprehension, and translation. Translators work sentence by sentence -- compound sentences create ambiguity about which clause modifies which. Stripe's error messages follow single-idea sentences: "Your card was declined." "Try a different payment method."
+
+4. **Prefer concrete nouns over abstract ones.** Abstract nouns force the reader to map the abstraction to something real. "Your uploaded resource" is abstract. "Your file" is concrete. "The authentication credential" is abstract. "Your password" is concrete. "The configuration parameters" is abstract. "Your settings" is concrete. Users think in concrete objects, not in system abstractions. Apple's Human Interface Guidelines consistently use concrete language: "your photo," "your message," "your password" -- never "the media asset," "the communication payload," "the credential."
+
+5. **Use the word the user would search for.** If users search for "dark mode," label the setting "Dark mode" -- not "Appearance theme" or "Display preferences." If users search for "delete my account," the menu item should say "Delete account" -- not "Account deactivation" or "Terminate membership." Google runs search query analysis on their support pages to identify the terms users actually type, then maps those terms directly to feature labels and help articles. This principle extends to error messages: "No internet connection" is what users would type into a search engine, not "Network connectivity unavailable."
+
+6. **Define technical terms on first use when they cannot be avoided.** Some terms have no plain alternative -- "two-factor authentication," "API key," "webhook" are genuinely specialized and the plain alternatives are longer and less precise. When these terms must appear in UI text, define them inline on first use. GitHub does this: "Fork -- create your own copy of this repository." Stripe does this: "API key -- a unique identifier that authenticates requests to Stripe's API." The definition should be one clause or one sentence. If the definition requires a paragraph, link to documentation instead.
+
+7. **Cut nominalizations -- use verb forms over noun forms.** Nominalizations are verbs turned into nouns: "make a decision" instead of "decide," "perform an analysis" instead of "analyze," "send a notification" instead of "notify." Nominalizations add words without adding meaning. They make sentences longer, more abstract, and harder to scan. The fix is mechanical: find the nominalization, extract the verb, rebuild the sentence around the verb.
+
+   | Nominalization (wordy)    | Verb form (concise) |
+   | ------------------------- | ------------------- |
+   | make a selection          | select              |
+   | perform a search          | search              |
+   | carry out an installation | install             |
+   | give authorization        | authorize           |
+   | reach a conclusion        | conclude            |
+   | take into consideration   | consider            |
+   | provide an explanation    | explain             |
+   | make an adjustment        | adjust              |
+
+## Details
+
+### Reading Level Targets by Audience
+
+Different audiences tolerate different reading levels, but the principle is the same: write at the lowest level the content allows.
+
+| Audience                  | Target Grade Level | Sentence Length | Example Product          |
+| ------------------------- | ------------------ | --------------- | ------------------------ |
+| General consumer          | Grade 6-8          | 12-15 words     | Airbnb, Instagram, Venmo |
+| Prosumer / small business | Grade 8-10         | 15-20 words     | Notion, Figma, Shopify   |
+| Developer tooling         | Grade 10-12        | 20-25 words     | Stripe API, GitHub API   |
+| Enterprise administration | Grade 10-12        | 15-20 words     | AWS Console, Salesforce  |
+
+Even at the developer level, plain language principles apply. Stripe's API documentation is technical but avoids unnecessary complexity: "Create a PaymentIntent" not "Instantiate a PaymentIntent object by invoking the creation endpoint." The technical audience does not need simpler concepts -- they need simpler phrasing of complex concepts.
+
+### Sentence Length Guidelines
+
+Research consistently shows that comprehension drops as sentence length increases:
+
+- **Under 14 words:** 90%+ comprehension on first read
+- **14-22 words:** 70-80% comprehension on first read
+- **23-30 words:** 50-60% comprehension on first read
+- **Over 30 words:** Below 50% comprehension on first read
+
+For UI text, the maximum sentence length should be 20 words. For mobile UI (where screen width constrains line length), target 12-15 words. For tooltips and toasts, target 8-12 words. Count the words in every sentence you write and split anything over the limit.
+
+### The Plain Language Audit
+
+To audit existing UI text for plain language compliance:
+
+1. Extract all user-facing strings from the codebase into a spreadsheet.
+2. Run each string through a readability scorer (Flesch-Kincaid or Hemingway).
+3. Flag any string above your target grade level.
+4. Check flagged strings against the jargon substitution table.
+5. Rewrite flagged strings using shorter sentences, simpler words, and concrete nouns.
+6. Re-score the rewritten strings to verify improvement.
+
+Gov.uk performed this audit across their entire government website and reduced the average reading level from grade 14 to grade 8. Support ticket volume dropped 30% in the first year after the plain language rewrite.
+
+### Anti-Patterns
+
+1. **The Thesaurus Trap.** Using unusual synonyms to avoid repeating common words. "Utilize" instead of "use" the second time, then "leverage" the third time, then "employ" the fourth. This variety confuses rather than clarifies -- the reader wonders if each synonym means something different. In UI text, consistency trumps variety. If the action is "save," use "save" every time. If the object is "project," call it "project" everywhere. Stripe uses "customer" consistently throughout their entire dashboard -- never "client," "user," or "account holder."
+
+2. **The Legalese Leak.** Legal or compliance language that bleeds into user-facing text. "By proceeding, you acknowledge and agree that the aforementioned data will be processed in accordance with our privacy policy as amended from time to time." No user reads this, and those who try cannot parse it. The fix: write the legal concept in plain language first, then have legal review for accuracy. "We'll use your data as described in our privacy policy" says the same thing in 12 words instead of 30. Apple's privacy labels accomplish this -- "Data Used to Track You" is legally accurate and readable at a fourth-grade level.
+
+3. **The Acronym Soup.** UI text filled with undefined acronyms: "Configure your SSO via SAML or OIDC in the IAM console." Each acronym is a speed bump that forces the reader to decode or search. The rule: spell out every acronym on first use in any given screen. If the screen uses more than two acronyms, the text is too technical for the audience. AWS documentation improves when it says "Single Sign-On (SSO)" on first mention, then uses "SSO" thereafter. For UI text (not documentation), consider whether the acronym is necessary at all -- "Sign in with your company account" may be better than "Configure SSO."
+
+4. **The Passive Abstraction.** Combining passive voice with abstract nouns to create maximally opaque sentences. "The configuration has been updated with the newly specified parameters" instead of "Your settings are saved." "An error was encountered during the processing of your request" instead of "Something went wrong. Try again." These sentences require the reader to mentally restructure the grammar to extract meaning. The fix: find the actor, find the action, put them in subject-verb order with concrete nouns.
+
+### Real-World Examples
+
+**Gov.uk's Plain Language Transformation.** The UK Government Digital Service rewrote the entire gov.uk website using plain language principles. Before: "If you are a foreign national seeking indefinite leave to remain in the United Kingdom, you must demonstrate that you have met the residency requirement." After: "To stay in the UK permanently, you need to have lived here for a certain amount of time." The before version reads at grade 16. The after version reads at grade 8. Both are legally accurate. The plain language version reduced phone calls to the immigration helpline by 35% because users could understand the requirements without assistance.
+
+**Stripe's Error Messages.** Stripe's payment error messages demonstrate plain language under pressure. When a card is declined, users are stressed and need immediate clarity. Stripe's messages: "Your card was declined. Try a different payment method or contact your bank." "Your card's expiration year is invalid." "Your card number is incomplete." Each message names the specific problem and (when possible) provides a specific next action. Compare with a legacy payment processor: "Error code 4001: Transaction declined by issuing bank. Please consult your financial institution regarding the status of your account." Same information, but the plain language version is actionable without decoding.
+
+**Notion's Feature Naming.** Notion's naming conventions demonstrate user-centered vocabulary. The product uses "page" (not "document"), "block" (not "content element"), "template" (not "scaffolding"), "share" (not "publish" or "distribute"), and "comment" (not "annotation" or "feedback item"). Each term was chosen because it maps to a concept users already understand. When Notion introduced databases, they called them "databases" -- a word every user knows -- rather than "structured data collections" or "relational tables." The simplicity of the naming makes a complex product feel approachable.
+
+**Apple's Privacy Labels.** Apple's App Store privacy labels translate complex data collection practices into plain language that any user can understand. Instead of "This application processes personally identifiable information for advertising attribution purposes," Apple's labels say "Data Used to Track You" and "Data Linked to You." Each label category uses a concrete icon and a two-to-four word description. The labels read at a fourth-grade level while remaining legally accurate -- proof that legal concepts can be expressed in plain language without sacrificing precision.
+
+## Source
+
+- plainlanguage.gov -- Federal Plain Language Guidelines, the definitive government standard for clear writing
+- NNGroup -- "How Users Read on the Web" (1997, updated 2020), eye-tracking evidence for scanning behavior
+- Flesch-Kincaid readability metrics -- standard measurement for reading level assessment
+- Gov.uk Content Design Manual -- https://www.gov.uk/guidance/content-design, evidence-based plain language practices
+- Krug, S. -- _Don't Make Me Think_ (2014), the case for simple language in interfaces
+- Google Material Design -- Writing guidelines, jargon elimination principles
+- Hemingway App -- http://hemingwayapp.com, practical readability scoring tool
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Run existing UI text through a readability scorer to establish a baseline.
+3. Apply jargon substitution, sentence splitting, and nominalization removal.
+4. Re-score rewritten text to verify it meets the target reading level.
+5. Verify your implementation against the anti-patterns listed above.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+
+## Success Criteria
+
+- All user-facing text scores at or below the target reading level for the product's audience.
+- No jargon appears in user-facing text without an inline definition on first use.
+- Every sentence in UI text contains one idea and is under 20 words.
+- Concrete nouns replace abstract ones throughout -- "your file" not "the uploaded resource."
+- Support ticket volume related to user confusion decreases after applying these principles.

package/dist/agents/skills/claude-code/ux-plain-language/skill.yaml

@@ -0,0 +1,34 @@
+name: ux-plain-language
+version: "1.0.0"
+description: Plain language for UI — reading level targeting, jargon elimination, sentence structure for scanning
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-microcopy-principles
+  - ux-writing-for-scanning
+  - ux-active-voice
+  - design-readability
+stack_signals: []
+keywords:
+  - plain-language
+  - readability
+  - jargon
+  - reading-level
+  - sentence-structure
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/ux-search-copy/SKILL.md

@@ -0,0 +1,154 @@
+# Search Copy
+
+> Search copy — placeholder text, zero-results messaging, autocomplete hints, search scope indicators, saved search patterns
+
+## When to Use
+
+- Writing placeholder text for search inputs across headers, sidebars, and command palettes
+- Designing zero-results states that distinguish no-data from no-match
+- Building autocomplete suggestion lists with labels and category headers
+- Creating advanced search interfaces with boolean operators and field qualifiers
+- Handling search scope -- searching within a project, a team, a document, or the whole product
+- Writing saved search patterns, default search names, and search history UI
+- NOT for: form field placeholders for data entry (use ux-form-labels)
+- NOT for: navigation menus and breadcrumbs (use ux-navigation-labels)
+- NOT for: filter interfaces attached to tables (use ux-data-table-copy)
+
+## Instructions
+
+1. **Placeholder text names the scope and shows what can be searched -- not just "Search..."** A bare "Search..." placeholder tells the user nothing about what the search covers or what types of queries it supports. "Search issues, projects, docs..." tells the user three things they can find. "Search by name, email, or team..." shows the query vocabulary. "Search files and folders..." scopes the search to a specific domain. GitHub's global search placeholder reads "Search or jump to..." -- acknowledging that the search bar serves dual function (search and navigation). Notion's quick find says "Search or jump to a page..." -- specific about the object type. The placeholder should answer "what will I find if I type here?" without requiring the user to experiment to discover the search's coverage.
+
+2. **Zero-results copy names what was searched and suggests what to try next.** "No results" is the minimum viable zero-results state. The ideal state names the query, provides context about where was searched, and offers an actionable next step. Pattern: "No results for '[query]' in [scope]. Try [suggestion]." Stripe's search shows: "No results for 'invoic' -- check the spelling or search for a different term." GitHub shows: "We couldn't find any repositories matching 'harnes-engineering' -- did you mean 'harness-engineering'?" The spell-correction suggestion is the highest-value addition to a zero-results state because it resolves the most common cause of zero results -- typos. When the product cannot offer a spell-correction suggestion, offer a scope-expansion suggestion: "No results in this project. Search all projects."
+
+3. **Autocomplete suggestions front-load the matching portion and distinguish result types with labels.** When a user types "pay" into a command palette, the suggestions should show the matching characters bold or highlighted at the start: "**Pay**ment methods," "**Pay**roll settings," "**Pay**outs." Front-loading makes the match scannable -- the user's eye can move down the list comparing only the suffix that differentiates results rather than reading each full suggestion. When autocomplete returns mixed result types (pages, files, people, commands), use category separators: "Pages," "Files," "People" as non-interactive group headers. Notion's quick find separates "Recently visited" from "Best matches." Linear's command palette separates "Actions" from "Pages" from "Issues." Category headers let the user scan to the type of result they want rather than reading every suggestion in order.
+
+4. **Scope indicators appear before the input and persist while the user types.** A scope chip or badge before the search input tells the user the search is constrained before they type -- not after they get unexpected results. The pattern: [Scope badge] [Input] -- "In Acme Corp: Search..." or "This repository: [input]." When the scope can be changed, the scope badge is clickable and shows a dropdown. GitHub's scoped search shows "This repository," "This organization," or "All of GitHub" as a dropdown before the input field. Linear's command palette shows "In Backlog" when opened from the backlog view. The scope must be visible at input focus -- discovering that a search was scoped after getting zero results is a frustrating experience that trains users to distrust the search system, even after the scope issue is understood.
+
+5. **Never use placeholder text as the primary label for a persistent search bar.** Placeholder text disappears the moment the user starts typing, making it useless as a label for users who are mid-query. A persistent search bar (always visible in the header, sidebar, or page) needs either a visible label above it or an accessible `aria-label` attribute. The placeholder in a persistent search bar is supplementary -- it shows scope or example queries, but the element's accessible name comes from the `aria-label`. A search input labeled only via placeholder fails WCAG 2.1 Success Criterion 1.3.5 (Identify Input Purpose). The correct pattern: `<input aria-label="Search issues and projects" placeholder="Search issues, projects, docs... (⌘K)">` where the `aria-label` provides the persistent accessible name and the placeholder provides supplementary scope and shortcut context.
+
+6. **Search shortcut hints belong in the placeholder, not a separate tooltip.** If the search bar is activatable via keyboard shortcut, show the shortcut in the placeholder text: "Search (⌘K)" or "Quick find (Ctrl+P)." This is the highest-visibility location for keyboard shortcut education -- the user sees it every time they look at the search bar, whether or not they are actively using it. Stripe's dashboard search shows "Search (⌘K)" in the placeholder. Linear's command palette shows the shortcut in the sidebar next to the search icon. The shortcut hint should disappear when the user starts typing (it is placeholder text, not a label), so it does not compete with the query the user is constructing. Do not put the shortcut hint in a tooltip or help text -- the barrier to discovering it there is too high for keyboard-first users who benefit most from it.
+
+7. **Saved searches use user-controlled names with system-suggested defaults.** When a search can be saved, the save action should prompt for a name. The system should suggest a name derived from the query: "Issues assigned to Jordan" (from `assignee:jordan is:open`) rather than "Saved search 1." The user should be able to rename it. Saved searches in the sidebar or list should show the query as secondary text below the name, so users can distinguish "High priority this week" from "High priority last month" without opening each saved search to inspect it. GitHub's saved searches (watched repositories, custom views) use user-provided names with the filter query visible on hover. Products that auto-generate names from query syntax give users a head start and reduce the cognitive overhead of naming every saved search manually.
+
+## Details
+
+### Search Input Anatomy
+
+A complete search input has five copyable elements, each with distinct purpose:
+
+| Element               | Purpose                 | Example                           |
+| --------------------- | ----------------------- | --------------------------------- |
+| Placeholder           | Scope and example query | "Search issues, members, docs..." |
+| Scope indicator       | Current search domain   | "In Acme Corp"                    |
+| Shortcut hint         | Keyboard activation     | "(⌘K)"                            |
+| Zero-results headline | Named query, no match   | "No results for 'invoic'"         |
+| Zero-results body     | Cause and next step     | "Check spelling or try 'invoice'" |
+
+Write all five for every search implementation. Missing elements are the most common source of search UX complaints in user research sessions. The zero-results states in particular are often left as an afterthought and shipped with generic copy that fails users at their highest moment of need.
+
+### Advanced Search Query Copy
+
+Products with advanced search syntax (field qualifiers, boolean operators, date ranges) require copy that teaches the syntax without overwhelming casual users. The pattern:
+
+- **Inline example in placeholder:** "author:Jordan is:open created:2024-01-01..today"
+- **Syntax help tooltip on focus:** Show a popover with 3-5 common qualifiers and examples
+- **Qualifier autocomplete:** When the user types `author:`, autocomplete with team members
+- **Query parsing feedback:** As the user types a qualifier, show a chip: `Author: Jordan` indicating the qualifier was recognized
+
+GitHub's issue search, Stripe's API log search, and Linear's advanced filter all use variations of this pattern. The key principle: teach the syntax at the point of use, not in a separate help article. Users who find help articles when encountering search friction are already context-switching out of their workflow -- in-context education at the moment of use keeps them in flow.
+
+### Review Checklist
+
+Use this checklist before shipping or reviewing any search implementation:
+
+| Check                     | Criteria                                        | Pass Condition                                                                |
+| ------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------- |
+| Placeholder specificity   | Names scope or searchable entity types          | Not just "Search..." -- includes 2-3 entity types or qualifier examples       |
+| Scope indicator           | Scope visible before user types                 | Scope badge or label appears at input focus, not only after zero results      |
+| Shortcut hint             | Keyboard shortcut shown in placeholder          | "(⌘K)" or equivalent appears in placeholder text when shortcut exists         |
+| Accessible label          | `aria-label` or visible `<label>` present       | Placeholder alone is not the accessible name; input has persistent aria-label |
+| Zero-results: query named | Zero-results state names the query              | "No results for '[query]'" not just "No results"                              |
+| Zero-results: next step   | Zero-results state offers actionable suggestion | Spell-correction, scope-expansion, or filter-clear suggestion provided        |
+| Autocomplete categories   | Mixed result types use section headers          | "Pages," "People," "Actions" headers separate result types                    |
+| Saved search names        | System suggests names from query syntax         | Auto-generated names from qualifiers, not "Saved search 1"                    |
+
+### Anti-Patterns
+
+1. **The Generic Placeholder.** A search input that says only "Search..." with no scope or example. Before: placeholder text "Search..." in a product with 12 searchable entity types. After: "Search issues, projects, and docs..." or "Search by name, tag, or status..." The generic placeholder is the most common search copy failure because it is the default state that ships without a content review. It communicates nothing about what is searchable, creates uncertainty about what will be returned, and misses the opportunity to teach users about the breadth of the search system at the exact moment they are deciding whether to use it.
+
+2. **The Empty Zero-State.** Zero-results states that show a blank space, just "No results," or an illustration with no text. Before: "No results" with an empty state illustration. After: "No results for 'harnes-engineering' -- check the spelling or try searching in all repositories." The difference between a helpful zero-results state and an unhelpful one is whether the user knows what to do next. An illustration without copy adds visual decoration but no information. A user who hits zero results is at peak frustration -- this is the moment when clear, specific copy has the highest impact on whether they persist or abandon.
+
+3. **The Scope Surprise.** A search that is scoped without telling the user, where they discover the scope only after getting zero results. Before: search input with no scope indicator, scoped to the current project. After: "In Project Apollo: Search issues..." with a clickable scope badge that expands to "Search all projects." Scope surprises are particularly damaging in products with hierarchical data (projects > teams > workspaces) where the user's mental model of "global" vs "local" search is ambiguous. After a scope surprise, users often assume the search system is broken or the data does not exist, when in fact both the data and the search work correctly -- the scope was simply not what the user expected.
+
+4. **The Placeholder Label.** A search input whose placeholder text is its only label -- the element has no `aria-label` and no visible `<label>` element. Before: `<input placeholder="Email address">` with no associated label. After: `<input aria-label="Search team members" placeholder="Search by name, email, or role...">`. The placeholder disappears on input, making the field unlabeled for users who have already started typing. Screen readers announce the accessible name, not the placeholder -- a search input with only placeholder text is announced as "edit text" with no context. WCAG 2.1 requires that all form inputs have persistent accessible labels; placeholder text does not satisfy this requirement and the violation is caught in standard accessibility audits.
+
+### Real-World Examples
+
+**GitHub search with scope indicators.** GitHub's search is the most complex search UX in the developer tools space because it spans repositories, users, organizations, code, commits, and issues -- all searchable with different syntax. The scope dropdown ("This repository / This organization / All of GitHub") is the key UX decision that makes the complexity manageable. When a user is inside a repository and opens search, the default scope is that repository, shown explicitly before the input. The user can expand scope with one click. Zero-results states in repository search show: "We searched through the entire repository history and couldn't find any matching code." The "entire repository history" phrasing reassures the user that the absence of results means the code genuinely does not exist, not that search failed or was scoped too narrowly.
+
+**Linear command palette.** Linear's command palette (opened via ⌘K) is the product's primary navigation, search, and action surface. The placeholder text is "Search or run a command..." -- acknowledging dual function. Autocomplete separates result types with labeled sections: "Actions," "Navigate to," "Issues," "Projects." The matching is fuzzy -- "crt iss" matches "Create issue" -- and the matched characters are highlighted in the suggestion. The shortcut hint for each action appears right-aligned in the suggestion row: "⌘⏎" for "Create and open." Linear's command palette is a benchmark for products where power users prefer keyboard-driven interaction, demonstrating that a search input can serve as the primary control surface for an entire product when the placeholder, scope, and autocomplete are all designed with intent.
+
+**Stripe Dashboard search.** Stripe's search bar (⌘K) is scoped to the user's current account by default and shows scope context: "Search in [Account name]." The zero-results state for a customer search shows: "No customers found for '[query]'. Check the name or email, or try searching by customer ID." The suggestion to try customer ID is learned behavior from Stripe's support data -- the most common reason for zero results in customer search is that the user is searching by a name they stored differently from how Stripe indexed it. Stripe also shows "Recent searches" and "Recent customers" in the search dropdown before the user types -- reducing the need for typing in the most common use cases and making the search bar a navigation shortcut as much as a search tool.
+
+**Notion quick find.** Notion's quick find (⌘P or ⌘K) searches across pages, databases, and linked databases in the current workspace. The placeholder is "Search or jump to a page..." -- "jump to" captures the navigation use case distinct from content search. Results are separated into "Recently visited" (no typing required) and "Best matches" (as the user types). Each result shows the page title, its parent in the hierarchy (e.g., "Team Space > Engineering"), and a relative timestamp. The hierarchy path is the critical detail -- Notion pages are nested, and a page named "Notes" could exist in 12 different parent pages. Without the hierarchy path, the user cannot distinguish search results with identical names and must open each to determine which is the correct one.
+
+### Copy Formulas Quick Reference
+
+These are fill-in-the-blank templates for the most common search copy patterns:
+
+- **Placeholder (entity types):** `Search [entity type 1], [entity type 2], [entity type 3]...`
+- **Placeholder (qualifiers):** `Search by [qualifier 1], [qualifier 2], or [qualifier 3]...`
+- **Placeholder with shortcut:** `Search [scope]... ([shortcut])`
+- **Scope indicator:** `In [Workspace / Project / Repository]: Search...`
+- **Scope dropdown label:** `This [repository / project / organization]` or `All of [product name]`
+- **Zero-results headline:** `No results for '[query]'`
+- **Zero-results body (typo):** `Check the spelling or try a different term.`
+- **Zero-results body (scope):** `Try expanding to all [entity types] across [product].`
+- **Zero-results with suggestion:** `Did you mean '[corrected query]'?`
+- **Autocomplete category header:** `[Entity type]` -- e.g., "Pages," "People," "Actions," "Issues"
+- **Saved search suggested name:** `[Entity type]s [qualifier description]` -- e.g., "Issues assigned to Jordan, open"
+- **Saved search list display:** `[Name] · [query summary]` -- e.g., "High priority · assignee:me priority:high"
+
+## Source
+
+- NNGroup -- "Search: Visible and Simple," https://www.nngroup.com/articles/search-visible-and-simple/
+- NNGroup -- "Solr Search: Dealing with No Search Results," https://www.nngroup.com/articles/no-results/
+- Morville, P. and Callender, J. -- _Search Patterns_ (2010), O'Reilly Media
+- WCAG 2.1 Success Criterion 1.3.5 -- Identify Input Purpose, https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html
+- Stripe -- Dashboard search UX (observable via product)
+- GitHub -- Search syntax documentation, https://docs.github.com/en/search-github/searching-on-github
+
+## Process
+
+1. **Define the search scope for this implementation.** Determine what entity types are searchable (issues, users, files, commands), what the default scope is (current project, all projects, global), and whether the user can change scope. Write the scope indicator copy and scope dropdown labels before writing the placeholder -- the scope shapes all other copy decisions. Confirm the scope behavior with the engineering team, because scoping behavior is often determined by backend indexing decisions that product and design may not be aware of.
+
+2. **Write the placeholder text using the correct pattern.** Use "Search [entity types]..." when the scope is broad and entity types are the key information. Use "Search by [qualifiers]..." when the search is structured and qualifier vocabulary is the key information. Include the keyboard shortcut if the input is shortcut-activatable. Keep the placeholder under 50 characters so it does not overflow on smaller viewports.
+
+3. **Write the zero-results state with four elements.** Every zero-results state needs: the named query ("No results for '[query]'"), the scope that was searched ("in this project" or "across all repositories"), the most likely cause (spell check, scope mismatch, filter conflict), and a suggested next step (try a different term, expand scope, clear filters). Review the most common zero-results queries in analytics before writing the suggestions -- product-specific data produces better suggestions than generic advice.
+
+4. **If the search supports advanced syntax, write the qualifier autocomplete prompts.** For each field qualifier (author:, assignee:, status:, date:), write the autocomplete prompt that appears when the user types the qualifier prefix. Confirm with engineering which qualifiers are supported and what values are valid. Write inline syntax examples for the top 3-5 most-used qualifiers and place them in the syntax help popover that appears on focus. Test the popover on mobile -- popovers that are too large obscure the input on small screens.
+
+5. **Define the saved search naming pattern.** Determine how the system generates suggested names from query syntax. Write the naming template: "Issues [qualifier description]" -- for example, "Issues assigned to Jordan, open" from `assignee:jordan is:open`. Confirm the rename interaction (inline edit or modal), the saved search list display format (name + query summary), and the maximum number of saved searches per user. Write the empty state for the saved search list ("No saved searches yet. Run a search and save it for quick access.") and the tooltip for the save action ("Save this search to your sidebar").
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Every search input has a placeholder that names the scope or searchable entity types -- not just "Search..." -- so users know what they can find before they type.
+- Zero-results states name the query that was searched, the scope that was covered, and offer a specific next step -- not just "No results."
+- Search scope is visible before the user types (via a scope badge or label at focus), not discovered only after receiving zero results.
+- All search inputs have accessible labels (`aria-label` or visible `<label>`) independent of placeholder text, satisfying WCAG 2.1 SC 1.3.5.
+- Autocomplete suggestions separate result types with labeled category headers when mixed entity types are returned, so users can scan to the type of result they want.
+- Keyboard shortcut hints are included in placeholder text when the search bar is shortcut-activatable, making shortcut discovery zero-friction for all users.
+- Saved searches display system-suggested names derived from query syntax and show the query as secondary text in the saved search list for disambiguation.
+
+## Voice Search and Mobile Search Considerations
+
+Voice-activated search inputs require placeholder text that acknowledges the voice input mode when active. On activation, the placeholder transitions from "Search issues..." to "Listening..." and then to a visual waveform or "Speak now" indicator. When voice recognition completes, the recognized query populates the input and the search executes, but a "Did you mean [query]?" prompt should appear if confidence is below a threshold -- the same spell-correction pattern applied to typed queries, but applied to recognition confidence.
+
+Mobile search inputs with a soft keyboard require careful copy density. The search results dropdown on mobile has roughly half the horizontal space of desktop, which means autocomplete suggestion text must be shorter. Apply the same entity-type and category conventions as desktop, but truncate suggestion text to 30-40 characters and use abbreviations where standard (e.g., "Proj." for "Project" in category headers). Test autocomplete suggestions on a physical device at the smallest supported screen size before shipping.
+
+Search within embedded contexts (search inside a modal, search inside a drawer panel, search within a command palette) requires scoping copy that reflects the constrained context. A search inside a "Add team members" modal should read "Search people..." not "Search..." -- the scope is already implied by the modal's purpose, but the placeholder still benefits from naming the entity type. In constrained contexts where the scope indicator would compete visually with the input, embed the scope in the placeholder: "Search team members by name or email."