Add docs for useSecret and useSecretItem hooks

Add comprehensive JSDoc to useSecret and useSecretItem to clarify parameters, return shapes, and behavior. Highlights: useSecret now documents that it combines a read subscription with saveSecret/deleteSecret that refresh the cache on success and that mutation helpers return a discriminated HookMutationResult (do not throw). useSecretItem docs explain includeValue:false (metadata-only, avoids iOS biometric prompt), that NotFoundError is surfaced as data:null, and include usage examples and @see references. No functional changes — only documentation improvements.

Author: mCodex

src/hooks/useSecret.ts

@@ -45,10 +45,32 @@ const normalizeMutationOptions = (
 /**
  * Maintains a secure item while exposing imperative helpers to mutate or refresh it.
  *
+ * Combines a read subscription (via {@link useSecretItem}) with `saveSecret` / `deleteSecret`
+ * helpers that automatically refresh the cached entry on success.
+ *
+ * @param key     - Identifier of the secret to track. Changing the key triggers a fresh fetch.
+ * @param options - Storage scoping plus hook flags (`skip`, `includeValue`).
+ * @returns A {@link UseSecretResult} with `data`/`error`/`isLoading`/`isPending` state and the
+ * `saveSecret`, `deleteSecret`, `refetch` helpers.
+ *
+ * @remarks
+ * - Mutation helpers never throw \u2014 they resolve with a {@link HookMutationResult} discriminated
+ *   union. Branch with `if (!result.success)`.
+ * - If you only need read access, prefer {@link useSecretItem} \u2014 lighter result shape.
+ *
  * @example
  * ```tsx
- * const secret = useSecret('refreshToken', { service: 'com.example.session' })
+ * const { data, isLoading, saveSecret, deleteSecret } = useSecret('refreshToken', {
+ *   service: 'com.example.session',
+ * })
+ *
+ * await saveSecret(nextToken)
+ * await deleteSecret()
  * ```
+ *
+ * @see {@link useSecretItem}
+ * @see {@link setItem}
+ * @see {@link deleteItem}
  */
 export function useSecret(
 	key: string,

src/hooks/useSecretItem.ts

@@ -26,6 +26,31 @@ export interface UseSecretItemResult extends AsyncState<SensitiveInfoItem> {
 
 /**
  * Fetches a single entry from the secure store and keeps the result in sync with the component.
+ *
+ * @param key     - Identifier of the entry to fetch. Changing the key triggers a fresh request.
+ * @param options - Storage scoping plus hook-only flags (`includeValue`, `skip`).
+ * @returns A {@link UseSecretItemResult} with `data`/`error`/`isLoading`/`isPending` state and a
+ * `refetch` helper.
+ *
+ * @remarks
+ * - Pass `includeValue: false` to fetch metadata only \u2014 cheaper, and on iOS this avoids the
+ *   biometric prompt. Use {@link useSecret} instead when you also need mutation helpers.
+ * - The hook absorbs `NotFoundError` from the underlying {@link getItem} call and surfaces it as
+ *   `data: null` \u2014 every other error appears in `error` as a {@link HookError}.
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, refetch } = useSecretItem('session-token', {
+ *   service: 'com.example.auth',
+ * })
+ *
+ * if (isLoading) return <Spinner />
+ * if (!data) return <SignInScreen />
+ * return <Dashboard token={data.value!} backend={data.metadata.backend} />
+ * ```
+ *
+ * @see {@link getItem}
+ * @see {@link useSecret}
  */
 export function useSecretItem(
 	key: string,