@ossiq/cli-darwin-x64 0.1.12 → 0.1.14

package/bin/ossiq/_internal/keyring-25.7.0.dist-info/entry_points.txt

@@ -0,0 +1,13 @@
+[console_scripts]
+keyring = keyring.cli:main
+
+[devpi_client]
+keyring = keyring.devpi_client
+
+[keyring.backends]
+KWallet = keyring.backends.kwallet
+SecretService = keyring.backends.SecretService
+Windows = keyring.backends.Windows
+chainer = keyring.backends.chainer
+libsecret = keyring.backends.libsecret
+macOS = keyring.backends.macOS

package/bin/ossiq/_internal/keyring-25.7.0.dist-info/licenses/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2025 <copyright holders>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/bin/ossiq/_internal/keyring-25.7.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+keyring

package/bin/ossiq/_internal/lark/grammars/common.lark

@@ -0,0 +1,59 @@
+// Basic terminals for common use
+
+
+//
+// Numbers
+//
+
+DIGIT: "0".."9"
+HEXDIGIT: "a".."f"|"A".."F"|DIGIT
+
+INT: DIGIT+
+SIGNED_INT: ["+"|"-"] INT
+DECIMAL: INT "." INT? | "." INT
+
+// float = /-?\d+(\.\d+)?([eE][+-]?\d+)?/
+_EXP: ("e"|"E") SIGNED_INT
+FLOAT: INT _EXP | DECIMAL _EXP?
+SIGNED_FLOAT: ["+"|"-"] FLOAT
+
+NUMBER: FLOAT | INT
+SIGNED_NUMBER: ["+"|"-"] NUMBER
+
+//
+// Strings
+//
+_STRING_INNER: /.*?/
+_STRING_ESC_INNER: _STRING_INNER /(?<!\\)(\\\\)*?/
+
+ESCAPED_STRING : "\"" _STRING_ESC_INNER "\""
+
+
+//
+// Names (Variables)
+//
+LCASE_LETTER: "a".."z"
+UCASE_LETTER: "A".."Z"
+
+LETTER: UCASE_LETTER | LCASE_LETTER
+WORD: LETTER+
+
+CNAME: ("_"|LETTER) ("_"|LETTER|DIGIT)*
+
+
+//
+// Whitespace
+//
+WS_INLINE: (" "|/\t/)+
+WS: /[ \t\f\r\n]/+
+
+CR : /\r/
+LF : /\n/
+NEWLINE: (CR? LF)+
+
+
+// Comments
+SH_COMMENT: /#[^\n]*/
+CPP_COMMENT: /\/\/[^\n]*/
+C_COMMENT: "/*" /(.|\n)*?/ "*/"
+SQL_COMMENT: /--[^\n]*/

package/bin/ossiq/_internal/lark/grammars/lark.lark

@@ -0,0 +1,62 @@
+# Lark grammar of Lark's syntax
+# Note: Lark is not bootstrapped, its parser is implemented in load_grammar.py
+
+start: (_item? _NL)* _item?
+
+_item: rule
+     | token
+     | statement
+
+rule: RULE rule_params priority? ":" expansions
+token: TOKEN token_params priority? ":" expansions
+
+rule_params: ["{" RULE ("," RULE)* "}"]
+token_params: ["{" TOKEN ("," TOKEN)* "}"]
+
+priority: "." NUMBER
+
+statement: "%ignore" expansions                    -> ignore
+         | "%import" import_path ["->" name]       -> import
+         | "%import" import_path name_list         -> multi_import
+         | "%override" rule                        -> override_rule
+         | "%declare" name+                        -> declare
+
+!import_path: "."? name ("." name)*
+name_list: "(" name ("," name)* ")"
+
+?expansions: alias (_VBAR alias)*
+
+?alias: expansion ["->" RULE]
+
+?expansion: expr*
+
+?expr: atom [OP | "~" NUMBER [".." NUMBER]]
+
+?atom: "(" expansions ")"
+     | "[" expansions "]" -> maybe
+     | value
+
+?value: STRING ".." STRING -> literal_range
+      | name
+      | (REGEXP | STRING) -> literal
+      | name "{" value ("," value)* "}" -> template_usage
+
+name: RULE
+    | TOKEN
+
+_VBAR: _NL? "|"
+OP: /[+*]|[?](?![a-z])/
+RULE: /!?[_?]?[a-z][_a-z0-9]*/
+TOKEN: /_?[A-Z][_A-Z0-9]*/
+STRING: _STRING "i"?
+REGEXP: /\/(?!\/)(\\\/|\\\\|[^\/])*?\/[imslux]*/
+_NL: /(\r?\n)+\s*/
+
+%import common.ESCAPED_STRING -> _STRING
+%import common.SIGNED_INT -> NUMBER
+%import common.WS_INLINE
+
+COMMENT: /\s*/ "//" /[^\n]/* | /\s*/ "#" /[^\n]/*
+
+%ignore WS_INLINE
+%ignore COMMENT

package/bin/ossiq/_internal/lark/grammars/python.lark

@@ -0,0 +1,302 @@
+// Python 3 grammar for Lark
+
+// This grammar should parse all python 3.x code successfully.
+
+// Adapted from: https://docs.python.org/3/reference/grammar.html
+
+// Start symbols for the grammar:
+//       single_input is a single interactive statement;
+//       file_input is a module or sequence of commands read from an input file;
+//       eval_input is the input for the eval() functions.
+// NB: compound_stmt in single_input is followed by extra NEWLINE!
+//
+
+single_input: _NEWLINE | simple_stmt | compound_stmt _NEWLINE
+file_input: (_NEWLINE | stmt)*
+eval_input: testlist _NEWLINE*
+
+decorator: "@" dotted_name [ "(" [arguments] ")" ] _NEWLINE
+decorators: decorator+
+decorated: decorators (classdef | funcdef | async_funcdef)
+
+async_funcdef: "async" funcdef
+funcdef: "def" name "(" [parameters] ")" ["->" test] ":" suite
+
+parameters: paramvalue ("," paramvalue)* ["," SLASH ("," paramvalue)*] ["," [starparams | kwparams]]
+          | starparams
+          | kwparams
+
+SLASH: "/" // Otherwise the it will completely disappear and it will be undisguisable in the result
+starparams: (starparam | starguard) poststarparams
+starparam: "*" typedparam
+starguard: "*"
+poststarparams: ("," paramvalue)* ["," kwparams]
+kwparams: "**" typedparam ","?
+
+?paramvalue: typedparam ("=" test)?
+?typedparam: name (":" test)?
+
+
+lambdef: "lambda" [lambda_params] ":" test
+lambdef_nocond: "lambda" [lambda_params] ":" test_nocond
+lambda_params: lambda_paramvalue ("," lambda_paramvalue)* ["," [lambda_starparams | lambda_kwparams]]
+          | lambda_starparams
+          | lambda_kwparams
+?lambda_paramvalue: name ("=" test)?
+lambda_starparams: "*" [name]  ("," lambda_paramvalue)* ["," [lambda_kwparams]]
+lambda_kwparams: "**" name ","?
+
+
+?stmt: simple_stmt | compound_stmt
+?simple_stmt: small_stmt (";" small_stmt)* [";"] _NEWLINE
+?small_stmt: (expr_stmt | assign_stmt | del_stmt | pass_stmt | flow_stmt | import_stmt | global_stmt | nonlocal_stmt | assert_stmt)
+expr_stmt: testlist_star_expr
+assign_stmt: annassign | augassign | assign
+
+annassign: testlist_star_expr ":" test ["=" test]
+assign: testlist_star_expr ("=" (yield_expr|testlist_star_expr))+
+augassign: testlist_star_expr augassign_op (yield_expr|testlist)
+!augassign_op: "+=" | "-=" | "*=" | "@=" | "/=" | "%=" | "&=" | "|=" | "^=" | "<<=" | ">>=" | "**=" | "//="
+?testlist_star_expr: test_or_star_expr
+                   | test_or_star_expr ("," test_or_star_expr)+ ","?  -> tuple
+                   | test_or_star_expr ","  -> tuple
+
+// For normal and annotated assignments, additional restrictions enforced by the interpreter
+del_stmt: "del" exprlist
+pass_stmt: "pass"
+?flow_stmt: break_stmt | continue_stmt | return_stmt | raise_stmt | yield_stmt
+break_stmt: "break"
+continue_stmt: "continue"
+return_stmt: "return" [testlist]
+yield_stmt: yield_expr
+raise_stmt: "raise" [test ["from" test]]
+import_stmt: import_name | import_from
+import_name: "import" dotted_as_names
+// note below: the ("." | "...") is necessary because "..." is tokenized as ELLIPSIS
+import_from: "from" (dots? dotted_name | dots) "import" ("*" | "(" import_as_names ")" | import_as_names)
+!dots: "."+
+import_as_name: name ["as" name]
+dotted_as_name: dotted_name ["as" name]
+import_as_names: import_as_name ("," import_as_name)* [","]
+dotted_as_names: dotted_as_name ("," dotted_as_name)*
+dotted_name: name ("." name)*
+global_stmt: "global" name ("," name)*
+nonlocal_stmt: "nonlocal" name ("," name)*
+assert_stmt: "assert" test ["," test]
+
+?compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt | match_stmt
+              | with_stmt | funcdef | classdef | decorated | async_stmt
+async_stmt: "async" (funcdef | with_stmt | for_stmt)
+if_stmt: "if" test ":" suite elifs ["else" ":" suite]
+elifs: elif_*
+elif_: "elif" test ":" suite
+while_stmt: "while" test ":" suite ["else" ":" suite]
+for_stmt: "for" exprlist "in" testlist ":" suite ["else" ":" suite]
+try_stmt: "try" ":" suite except_clauses ["else" ":" suite] [finally]
+        | "try" ":" suite finally   -> try_finally
+finally: "finally" ":" suite
+except_clauses: except_clause+
+except_clause: "except" [test ["as" name]] ":" suite
+// NB compile.c makes sure that the default except clause is last
+
+
+with_stmt: "with" with_items ":" suite
+with_items: with_item ("," with_item)*
+with_item: test ["as" name]
+
+match_stmt: "match" test ":" _NEWLINE _INDENT case+ _DEDENT
+
+case: "case" pattern ["if" test] ":" suite
+
+?pattern: sequence_item_pattern "," _sequence_pattern -> sequence_pattern
+        | as_pattern
+?as_pattern: or_pattern ("as" NAME)?
+?or_pattern: closed_pattern ("|" closed_pattern)*
+?closed_pattern: literal_pattern
+               | NAME -> capture_pattern
+               | "_" -> any_pattern
+               | attr_pattern
+               | "(" as_pattern ")"
+               | "[" _sequence_pattern "]" -> sequence_pattern
+               | "(" (sequence_item_pattern "," _sequence_pattern)? ")" -> sequence_pattern
+               | "{" (mapping_item_pattern ("," mapping_item_pattern)* ","?)?"}" -> mapping_pattern
+               | "{" (mapping_item_pattern ("," mapping_item_pattern)* ",")? "**" NAME ","? "}" -> mapping_star_pattern
+               | class_pattern
+
+literal_pattern: inner_literal_pattern
+
+?inner_literal_pattern: "None" -> const_none
+                      | "True" -> const_true
+                      | "False" -> const_false
+                      | STRING -> string
+                      | number
+
+attr_pattern: NAME ("." NAME)+ -> value
+
+name_or_attr_pattern: NAME ("." NAME)* -> value
+
+mapping_item_pattern: (literal_pattern|attr_pattern) ":" as_pattern
+
+_sequence_pattern: (sequence_item_pattern ("," sequence_item_pattern)* ","?)?
+?sequence_item_pattern: as_pattern
+                      | "*" NAME -> star_pattern
+
+class_pattern: name_or_attr_pattern "(" [arguments_pattern ","?] ")"
+arguments_pattern: pos_arg_pattern ["," keyws_arg_pattern]
+                 | keyws_arg_pattern -> no_pos_arguments
+
+pos_arg_pattern: as_pattern ("," as_pattern)*
+keyws_arg_pattern: keyw_arg_pattern ("," keyw_arg_pattern)*
+keyw_arg_pattern: NAME "=" as_pattern
+
+
+
+suite: simple_stmt | _NEWLINE _INDENT stmt+ _DEDENT
+
+?test: or_test ("if" or_test "else" test)?
+     | lambdef
+     | assign_expr
+
+assign_expr: name ":=" test
+
+?test_nocond: or_test | lambdef_nocond
+
+?or_test: and_test ("or" and_test)*
+?and_test: not_test_ ("and" not_test_)*
+?not_test_: "not" not_test_ -> not_test
+         | comparison
+?comparison: expr (comp_op expr)*
+star_expr: "*" expr
+
+?expr: or_expr
+?or_expr: xor_expr ("|" xor_expr)*
+?xor_expr: and_expr ("^" and_expr)*
+?and_expr: shift_expr ("&" shift_expr)*
+?shift_expr: arith_expr (_shift_op arith_expr)*
+?arith_expr: term (_add_op term)*
+?term: factor (_mul_op factor)*
+?factor: _unary_op factor | power
+
+!_unary_op: "+"|"-"|"~"
+!_add_op: "+"|"-"
+!_shift_op: "<<"|">>"
+!_mul_op: "*"|"@"|"/"|"%"|"//"
+// <> isn't actually a valid comparison operator in Python. It's here for the
+// sake of a __future__ import described in PEP 401 (which really works :-)
+!comp_op: "<"|">"|"=="|">="|"<="|"<>"|"!="|"in"|"not" "in"|"is"|"is" "not"
+
+?power: await_expr ("**" factor)?
+?await_expr: AWAIT? atom_expr
+AWAIT: "await"
+
+?atom_expr: atom_expr "(" [arguments] ")"      -> funccall
+          | atom_expr "[" subscriptlist "]"  -> getitem
+          | atom_expr "." name               -> getattr
+          | atom
+
+?atom: "(" yield_expr ")"
+     | "(" _tuple_inner? ")" -> tuple
+     | "(" comprehension{test_or_star_expr} ")" -> tuple_comprehension
+     | "[" _exprlist? "]"  -> list
+     | "[" comprehension{test_or_star_expr} "]"  -> list_comprehension
+     | "{" _dict_exprlist? "}" -> dict
+     | "{" comprehension{key_value} "}" -> dict_comprehension
+     | "{" _exprlist "}" -> set
+     | "{" comprehension{test} "}" -> set_comprehension
+     | name -> var
+     | number
+     | string_concat
+     | "(" test ")"
+     | "..." -> ellipsis
+     | "None"    -> const_none
+     | "True"    -> const_true
+     | "False"   -> const_false
+
+
+?string_concat: string+
+
+_tuple_inner: test_or_star_expr (("," test_or_star_expr)+ [","] | ",")
+
+?test_or_star_expr: test
+                 | star_expr
+
+?subscriptlist: subscript
+              | subscript (("," subscript)+ [","] | ",") -> subscript_tuple
+?subscript: test | ([test] ":" [test] [sliceop]) -> slice
+sliceop: ":" [test]
+?exprlist: (expr|star_expr)
+         | (expr|star_expr) (("," (expr|star_expr))+ [","]|",")
+?testlist: test | testlist_tuple
+testlist_tuple: test (("," test)+ [","] | ",")
+_dict_exprlist: (key_value | "**" expr) ("," (key_value | "**" expr))* [","]
+
+key_value: test ":"  test
+
+_exprlist: test_or_star_expr (","  test_or_star_expr)* [","]
+
+classdef: "class" name ["(" [arguments] ")"] ":" suite
+
+
+
+arguments: argvalue ("," argvalue)*  ("," [ starargs | kwargs])?
+         | starargs
+         | kwargs
+         | comprehension{test}
+
+starargs: stararg ("," stararg)* ("," argvalue)* ["," kwargs]
+stararg: "*" test
+kwargs: "**" test ("," argvalue)*
+
+?argvalue: test ("=" test)?
+
+
+comprehension{comp_result}: comp_result comp_fors [comp_if]
+comp_fors: comp_for+
+comp_for: [ASYNC] "for" exprlist "in" or_test
+ASYNC: "async"
+?comp_if: "if" test_nocond
+
+// not used in grammar, but may appear in "node" passed from Parser to Compiler
+encoding_decl: name
+
+yield_expr: "yield" [testlist]
+          | "yield" "from" test -> yield_from
+
+number: DEC_NUMBER | HEX_NUMBER | BIN_NUMBER | OCT_NUMBER | FLOAT_NUMBER | IMAG_NUMBER
+string: STRING | LONG_STRING
+
+// Other terminals
+
+_NEWLINE: ( /\r?\n[\t ]*/ | COMMENT )+
+
+%ignore /[\t \f]+/  // WS
+%ignore /\\[\t \f]*\r?\n/   // LINE_CONT
+%ignore COMMENT
+%declare _INDENT _DEDENT
+
+
+// Python terminals
+
+!name: NAME | "match" | "case"
+NAME: /[^\W\d]\w*/
+COMMENT: /#[^\n]*/
+
+STRING: /([ubf]?r?|r[ubf])("(?!"").*?(?<!\\)(\\\\)*?"|'(?!'').*?(?<!\\)(\\\\)*?')/i
+LONG_STRING: /([ubf]?r?|r[ubf])(""".*?(?<!\\)(\\\\)*?"""|'''.*?(?<!\\)(\\\\)*?''')/is
+
+_SPECIAL_DEC: "0".."9"        ("_"?  "0".."9"                       )*
+DEC_NUMBER:   "1".."9"        ("_"?  "0".."9"                       )*
+          |   "0"             ("_"?  "0"                            )* /(?![1-9])/
+HEX_NUMBER.2: "0" ("x" | "X") ("_"? ("0".."9" | "a".."f" | "A".."F"))+
+OCT_NUMBER.2: "0" ("o" | "O") ("_"?  "0".."7"                       )+
+BIN_NUMBER.2: "0" ("b" | "B") ("_"?  "0".."1"                       )+
+
+_EXP: ("e"|"E") ["+" | "-"] _SPECIAL_DEC
+DECIMAL: "." _SPECIAL_DEC | _SPECIAL_DEC "." _SPECIAL_DEC?
+FLOAT_NUMBER.2: _SPECIAL_DEC _EXP | DECIMAL _EXP?
+IMAG_NUMBER.2: (_SPECIAL_DEC      | FLOAT_NUMBER) ("J" | "j")
+
+
+// Comma-separated list (with an optional trailing comma)
+cs_list{item}: item ("," item)* ","?
+_cs_list{item}: item ("," item)* ","?

package/bin/ossiq/_internal/lark/grammars/unicode.lark

@@ -0,0 +1,7 @@
+// TODO: LETTER, WORD, etc.
+
+//
+// Whitespace
+//
+WS_INLINE: /[ \t\xa0]/+
+WS: /[ \t\xa0\f\r\n]/+

package/bin/ossiq/_internal/ossiq/data/SKILL.md

@@ -13,9 +13,15 @@ description: >-
 OSS IQ is a **local CLI tool** — it runs entirely on your machine and does not
 send any project data to external services. All analysis is performed locally.
 
-Run via `uvx ossiq` (no install needed, works from any directory) or bare `ossiq` if already installed.
+Run OSS IQ as `{{ossiq}}`, exactly as the commands below spell it; it works from any directory.
 
-**GitHub rate limits:** Without a token, GitHub's API allows 60 req/hr. If you hit rate limits, the user should run `ossiq install skills <tool> --github-token <token>` once to store the token in `~/.ossiq/config` (classic PAT, no scopes needed for public repos raises the limit to 5 000 req/hr). Do not ask the user to pass it manually on every command.
+**GitHub rate limits:** Without a login, GitHub's API allows 60 req/hr; logged in it allows 5 000. If you hit rate limits, or OSS IQ prints a GitHub login code, log in with a one-time code. Never ask the user for a token or put one on a command line.
+
+1. Run `{{ossiq}} auth login --no-wait`. It prints a URL and a code and exits with status 75, which means "waiting for approval", not failure.
+2. Show the URL and code to the user exactly as printed, and wait until they say they approved it on GitHub.
+3. Run `{{ossiq}} auth login --resume`. Exit 0 means logged in; 75 again means it is not approved yet. A code expires after about 15 minutes: go back to step 1 for a new one.
+
+Through the MCP server, a tool result with `auth_status: PENDING_USER_ACTION` carries the same URL and code. Relay them, wait for the user, then call the same tool again. The login is kept in the system keyring (`{{ossiq}} auth status` shows it, `{{ossiq}} auth logout` removes it). Without a keyring, or in CI, set `OSSIQ_GITHUB_TOKEN` in the environment instead.
 
 OSS IQ scores dependency health: drift, CVEs, maintainer/bus-factor risk,
 typosquat signals, and a solver-recommended version. Run it **before** you
@@ -23,9 +29,9 @@ change a project's dependencies and do what the `next_action` says.
 
 Either call the CLI (below) or, if an MCP server named `ossiq` is connected, call
 the equivalent tools `ossiq_evaluate_dependency` / `ossiq_evaluate_updates`. Prefer these (or
-`--format agent`). If you need a file to hand over instead, `ossiq export` writes the standard
+`--format agent`). If you need a file to hand over instead, `{{ossiq}} export` writes the standard
 profile - every direct dependency, the transitives that need attention, decision fields only.
-`ossiq export --full` adds every transitive, the dependency tree and raw upstream signals; it is for
+`{{ossiq}} export --full` adds every transitive, the dependency tree and raw upstream signals; it is for
 dashboards and archives and several times larger, so don't feed it to an agent.
 
 ## Tell OSS IQ which runtime the project runs on
@@ -51,7 +57,7 @@ The runtime you state is still held to the project's declared floor (`engines.no
 Before introducing a package, run:
 
 ```bash
-uvx ossiq info <package> <project_path> --format agent
+{{ossiq}} info <package> <project_path> --format agent
 ```
 
 Example output:
@@ -76,18 +82,22 @@ installed in the project (not a prospective add) — see the version ladder belo
 
 `next_action` for an add is `install`, `install with caution`, or `do not install`.
 
+`do not install` includes a package its registry deprecated, archived or quarantined, and a
+deprecated release requested by `version`. `reasons` quotes the registry's own note, which
+usually names the replacement: look for that alternative instead of forcing the install.
+
 ## When updating existing dependencies
 
 Before bumping versions, run:
 
 ```bash
-uvx ossiq status <project_path> --format agent
+{{ossiq}} status <project_path> --format agent
 ```
 
 By default this targets the `standard` tier of the update pyramid (plain drift, inside each
 package's declared range). Pass `--update-strategy security` for the smallest diff that clears
 known CVEs, or `latest`/`cutting-edge` to also widen constraints / admit prereleases — see
-`ossiq status --help`. The MCP tool `ossiq_evaluate_updates` takes the same `update_strategy`
+`{{ossiq}} status --help`. The MCP tool `ossiq_evaluate_updates` takes the same `update_strategy`
 argument.
 
 Example output:
@@ -130,17 +140,21 @@ Example output:
 ```
 
 The top-level `next_action` is the most urgent one across the `updates` list, or
-`no action needed` when the list is empty. Each entry's `next_action` is one of:
+`no action needed` when no entry has an action due. Each entry's `next_action` is one of:
 
 - **Check for the Fix** — a known CVE that `to` does not clear (or there is no `to`); check for a
   patched release.
-- **Find alternative** — the package is gone or its upstream is abandoned/deprecated; migrate off it.
+- **Find alternative** — the package is gone, its registry deprecated, archived or quarantined it,
+  or its upstream is abandoned/deprecated; migrate off it. A newer release of such a package does
+  not help.
 - **Consider alternative** — the upstream is winding down; plan a migration.
 - **Check Release Notes** — a major version behind; review breaking changes before the bump.
-- **Update Immediately** — a minor/patch behind, or a recommended version exists; bump it.
+- **Update Immediately** — a minor/patch behind, or a recommended version exists; bump it. An
+  entry that also carries `requires_constraint_widening: true` reads this way when `apply` writes
+  the wider range itself, after a confirmation.
 - **Constrained. Check newer version** — a minor/patch behind, but the declared range
-  (e.g. `~7.3.0`) admits no newer version, or the CVE fix in `to` needs it widened; widening the
-  range is the real next step.
+  (e.g. `~7.3.0`) admits no newer version, or the CVE fix in `to` needs it widened and `apply`
+  would not widen it on its own; widening the range is the real next step.
 - **Withheld by strategy** — a minor/patch behind, and the range admits a bump, but the run's
   `--update-strategy` tier admitted no motive to take it. Nothing is wrong with the package;
   `strategy_withheld_reason` names the lowest tier that would move it.
@@ -165,6 +179,15 @@ than its registry name — npm aliases (`"uuid-v7": "npm:uuid@^7.0.0"`) are the
 Two aliases of one package produce two entries sharing `"package"`, so `dependency_name` is what
 tells you which declaration an entry answers for and which line to edit.
 
+`unresolved_peers` appears (npm only) when the package declares a peer that nothing within its
+reach can satisfy, so the package may fail to load. It appears whatever the entry's `next_action`
+says, `no action needed` included. Each item gives the peer's `package` and `spec`, whether it is
+`optional`, and `installed_elsewhere`: the versions installed out of reach, empty when the peer is
+installed nowhere. When a copy that satisfies `spec` is installed elsewhere, the top-level
+`peer_repairs` lists what `{{ossiq}} apply` adds to the manifest to fix it. Don't read
+`no action needed` as clean for such a package: run `{{ossiq}} plan` to review the repair, then
+`{{ossiq}} apply`.
+
 ### Module-system and API breaks
 
 A recommended version is not always drop-in. Semver alone can't see an npm package going
@@ -212,8 +235,11 @@ choice (avoids known-CVE and too-fresh versions) — **unless the entry also car
 `"requires_constraint_widening": true`**. That flag means `to` is only reachable by
 widening the manifest's declared range first (`==1.10.13` admits nothing past
 1.10.13, so `1.10.26` needs a wider specifier, not just a straight rewrite of the
-pin). `ossiq update`/`ossiq apply` will not write such an entry on their own —
-widen the constraint by hand, then re-run the command.
+pin). `latest` and `cutting-edge` write such picks after a confirmation prompt. At the other
+tiers `{{ossiq}} update`/`{{ossiq}} apply` will not write one on their own — widen the
+constraint by hand, then re-run the command — unless the entry also carries
+`"widening_authorized": true`. That means a CVE or end-of-life motive carried the pick past
+the tier, so they write it after the same prompt.
 
 ### Engine/runtime compatibility
 
@@ -247,11 +273,11 @@ version it was checked against instead of leaving it a silent runtime failure.
 ## Before applying an update to a specific version
 
 `to` above is OSS IQ's own recommendation. If you (or the user) want to go to a *different*
-version — one `ossiq status`/`ossiq_evaluate_updates` didn't propose — check it first instead of
+version — one `{{ossiq}} status`/`ossiq_evaluate_updates` didn't propose — check it first instead of
 discovering a break via test failure:
 
 ```bash
-uvx ossiq update-context <package> <project_path> --to <version>
+{{ossiq}} update-context <package> <project_path> --to <version>
 ```
 
 or, over MCP, `ossiq_update_context` with `{"package": ..., "target_version": ..., "runtime": ...}`. `target_version`