From e7e68a43809f7a2b31aa6813a8f2b8b0b4afe0d2 Mon Sep 17 00:00:00 2001
From: Philippe Serhal <philippe.serhal@gmail.com>
Date: Sun, 22 Feb 2026 22:47:44 -0500
Subject: [PATCH] chore: remove unnecessary @public annotations and guidelines

knip supports this now; this is outdated information
---
 CONTRIBUTING.md                     | 12 ------------
 app/composables/useActiveTocItem.ts |  1 -
 app/composables/useMarkdown.ts      |  1 -
 server/utils/provenance.ts          |  1 -
 server/utils/skills.ts              |  3 ---
 shared/schemas/blog.ts              |  1 -
 shared/schemas/user.ts              |  2 --
 shared/types/npm-registry.ts        |  1 -
 shared/utils/constants.ts           |  2 --
 shared/utils/npm.ts                 |  1 -
 10 files changed, 25 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e0c605e40..9020552d0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -289,18 +289,6 @@ import { hasProtocol } from 'ufo'
 | Constants        | SCREAMING_SNAKE_CASE     | `NPM_REGISTRY`, `ALLOWED_TAGS` |
 | Types/Interfaces | PascalCase               | `NpmSearchResponse`            |
 
-> [!TIP]
-> Exports in `app/composables/`, `app/utils/`, and `server/utils/` are auto-imported by Nuxt. To prevent [knip](https://knip.dev/) from flagging them as unused, add a `@public` JSDoc annotation:
->
-> ```typescript
-> /**
->  * @public
->  */
-> export function myAutoImportedFunction() {
->   // ...
-> }
-> ```
-
 ### Vue components
 
 - Use Composition API with `<script setup lang="ts">`
diff --git a/app/composables/useActiveTocItem.ts b/app/composables/useActiveTocItem.ts
index 7807999a9..b1343b083 100644
--- a/app/composables/useActiveTocItem.ts
+++ b/app/composables/useActiveTocItem.ts
@@ -7,7 +7,6 @@ import type { Ref } from 'vue'
  *
  * @param toc - Reactive array of TOC items
  * @returns Object containing activeId
- * @public
  */
 export function useActiveTocItem(toc: Ref<TocItem[]>) {
   const activeId = shallowRef<string | null>(null)
diff --git a/app/composables/useMarkdown.ts b/app/composables/useMarkdown.ts
index a7a86f6fb..57048f847 100644
--- a/app/composables/useMarkdown.ts
+++ b/app/composables/useMarkdown.ts
@@ -8,7 +8,6 @@ interface UseMarkdownOptions {
   packageName?: string
 }
 
-/** @public */
 export function useMarkdown(options: MaybeRefOrGetter<UseMarkdownOptions>) {
   return computed(() => parseMarkdown(toValue(options)))
 }
diff --git a/server/utils/provenance.ts b/server/utils/provenance.ts
index 796b45c36..76ad4ecef 100644
--- a/server/utils/provenance.ts
+++ b/server/utils/provenance.ts
@@ -90,7 +90,6 @@ function repoUrlToBlobUrl(repository: string, path: string, ref = 'main'): strin
 /**
  * Parse npm attestations API response into ProvenanceDetails.
  * Prefers SLSA provenance v1; falls back to v0.2 for provider label and ledger only (no source commit/build file from v0.2).
- * @public
  */
 export function parseAttestationToProvenanceDetails(response: unknown): ProvenanceDetails | null {
   const body = response as NpmAttestationsResponse
diff --git a/server/utils/skills.ts b/server/utils/skills.ts
index 611c8653f..89b209147 100644
--- a/server/utils/skills.ts
+++ b/server/utils/skills.ts
@@ -73,7 +73,6 @@ export interface SkillDirInfo {
 /**
  * Find skill directories in a package file tree.
  * Returns skill names and their children for file counting.
- * @public
  */
 export function findSkillDirs(tree: PackageFileTree[]): SkillDirInfo[] {
   const skillsDir = tree.find(node => node.type === 'directory' && node.name === 'skills')
@@ -176,7 +175,6 @@ export function validateSkill(frontmatter: SkillFrontmatter): SkillWarning[] {
 
 /**
  * Fetch skill list with frontmatter for discovery endpoint.
- * @public
  */
 export async function fetchSkillsList(
   packageName: string,
@@ -215,7 +213,6 @@ export interface WellKnownSkillItem {
 
 /**
  * Fetch skill list for well-known index.json format (CLI compatibility).
- * @public
  */
 export async function fetchSkillsListForWellKnown(
   packageName: string,
diff --git a/shared/schemas/blog.ts b/shared/schemas/blog.ts
index 5b1670d12..587bf3288 100644
--- a/shared/schemas/blog.ts
+++ b/shared/schemas/blog.ts
@@ -34,5 +34,4 @@ export interface ResolvedAuthor extends Author {
 /**
  * Inferred type for blog post frontmatter
  */
-/** @public */
 export type BlogPostFrontmatter = InferOutput<typeof BlogPostSchema>
diff --git a/shared/schemas/user.ts b/shared/schemas/user.ts
index a51cec6ad..0a4d81e0f 100644
--- a/shared/schemas/user.ts
+++ b/shared/schemas/user.ts
@@ -21,7 +21,5 @@ export const GravatarQuerySchema = v.object({
   username: NpmUsernameSchema,
 })
 
-/** @public */
 export type NpmUsername = v.InferOutput<typeof NpmUsernameSchema>
-/** @public */
 export type GravatarQuery = v.InferOutput<typeof GravatarQuerySchema>
diff --git a/shared/types/npm-registry.ts b/shared/types/npm-registry.ts
index 7f414e53f..00558913c 100644
--- a/shared/types/npm-registry.ts
+++ b/shared/types/npm-registry.ts
@@ -233,7 +233,6 @@ export interface NpmVersionDist {
 /**
  * Parsed provenance details for display (from attestation bundle SLSA predicate).
  * Used by the provenance API and PackageProvenanceSection.
- * @public
  */
 export interface ProvenanceDetails {
   /** Provider ID (e.g. "github", "gitlab") */
diff --git a/shared/utils/constants.ts b/shared/utils/constants.ts
index 1d3575673..82d492658 100644
--- a/shared/utils/constants.ts
+++ b/shared/utils/constants.ts
@@ -31,9 +31,7 @@ export const ERROR_SUGGESTIONS_FETCH_FAILED = 'Failed to fetch suggestions.'
 export const ERROR_SKILLS_FETCH_FAILED = 'Failed to fetch skills.'
 export const ERROR_SKILL_NOT_FOUND = 'Skill not found.'
 export const ERROR_SKILL_FILE_NOT_FOUND = 'Skill file not found.'
-/** @public */
 export const ERROR_GRAVATAR_FETCH_FAILED = 'Failed to fetch Gravatar profile.'
-/** @public */
 export const ERROR_GRAVATAR_EMAIL_UNAVAILABLE = "User's email not accessible."
 export const ERROR_NEED_REAUTH = 'User needs to reauthenticate'
 
diff --git a/shared/utils/npm.ts b/shared/utils/npm.ts
index 54fb00730..bfb8dc7a4 100644
--- a/shared/utils/npm.ts
+++ b/shared/utils/npm.ts
@@ -52,7 +52,6 @@ export function assertValidPackageName(name: string): void {
 /**
  * Validate an npm username and throw an HTTP error if invalid.
  * Uses a regular expression to check against npm naming rules.
- * @public
  */
 export function assertValidUsername(username: string): void {
   if (!username || username.length > NPM_USERNAME_MAX_LENGTH || !NPM_USERNAME_RE.test(username)) {