Phase 2 spec: structured read-only hint view

Hint grammar taken from slackrepo's parser: search order, recognised
keys, ARCH-resolved downloads, forced checksum skip, the REQUIRES
computation, USERADD/GROUPADD defaults, pragmas. The detail pane shows
hints as sections, never the raw file. NODOWNLOAD=yes is shown as
DOWNLOAD="no"; phase 4 makes mkhint write DOWNLOAD="no".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2 files changed, 54 insertions, 9 deletions

diff --git a/docs/superpowers/specs/2026-10-19-sb-builder-phase1-design.md b/docs/superpowers/specs/2026-10-19-sb-builder-phase1-design.md
index b85e8fd..b957ae0 100644
--- a/docs/superpowers/specs/2026-10-19-sb-builder-phase1-design.md
+++ b/docs/superpowers/specs/2026-10-19-sb-builder-phase1-design.md
@@ -23,7 +23,9 @@ Each phase gets its own spec, plan and implementation cycle.
 3. **Full repo rebuild**: `slackrepo_setup_SBo-danix.sh`, destructive, guarded.
 4. **Hints**: mkhint browse, edit, update, create, `-F`, diff before save.
    Requires non-interactive flags in mkhint (it has about 10 `read -p`
-   prompts and wraps slackrepo at `mkhint:1798`).
+   prompts and wraps slackrepo at `mkhint:1798`). Also: `--no-dl` must write
+   `DOWNLOAD="no"`, which slackrepo reads, instead of `NODOWNLOAD=yes`,
+   which it does not (keep reading old `NODOWNLOAD` lines for the NoDL column).
 5. **Orphans**: SBo orphan discovery (`EMAIL="NOEMAIL"` in `.info`, the
    `sbo-orphans` logic from slackbuilds-superrepo), including orphaned deps
    in REQUIRES. Needs an SBo-stable tree, which is not on the VM today.
diff --git a/docs/superpowers/specs/2026-10-19-sb-builder-phase2-design.md b/docs/superpowers/specs/2026-10-19-sb-builder-phase2-design.md
index f622d30..dbac1f4 100644
--- a/docs/superpowers/specs/2026-10-19-sb-builder-phase2-design.md
+++ b/docs/superpowers/specs/2026-10-19-sb-builder-phase2-design.md
@@ -39,7 +39,21 @@ Verified on the VM and in the slackrepo source (`~/Programming/GIT/GITHUB/slackr
   (`category/pkg`); `buildresults` holds the last `result` per itemid
   (`ok`, `failed`, `bad`, `aborted`, `removed`). 213 of 799 `buildresults`
   rows have legacy keys without a `/` and match no package.
-- Hints: `/etc/slackrepo/SBo-danix/hintfiles/<pkg>.hint`, 623 of them.
+- Hints: 623 in `/etc/slackrepo/SBo-danix/hintfiles/`; the default hint dir
+  (`default_hintfiles/15.0`) is empty. Real usage: 594 `DELREQUIRES`, 13 each
+  of `VERSION`, `DOWNLOAD`, `MD5SUM`, `ARCH`, 1 `OPTIONS`.
+- Hint grammar (`libexec/functions.d/parsefunctions.sh:405-640`,
+  `man/man5/slackrepo.hint.5`): slackrepo searches `<SBREPO>/<cat>/<pkg>/`,
+  `HINTDIR/`, `HINTDIR/<cat>/<pkg>/`, `DEFAULT_HINTDIR/`,
+  `DEFAULT_HINTDIR/<cat>/<pkg>/` for `<pkg>.hint`, first match wins, and
+  sources it. Recognised keys: `SKIP VERSION OPTIONS GROUPADD USERADD
+  NOWARNING NOWARNINGS ADDREQUIRES DELREQUIRES BUILDTIME CONFLICTS INSTALL
+  NUMJOBS ANSWER CLEANUP PRAGMA SPECIAL ARCH DOWNLOAD MD5SUM SHA256SUM`, plus
+  `DOWNLOAD_<arch>`, `MD5SUM_<arch>`, `SHA256SUM_<arch>` resolved through
+  `ARCH`. The man page says `ANSWERS`; the code reads `ANSWER`.
+- mkhint `--no-dl` writes `NODOWNLOAD=yes`, which slackrepo does not read
+  (its switch is `DOWNLOAD="no"`). No current hint has it. Phase 4 changes
+  mkhint to write `DOWNLOAD="no"`.
 
 ## Part 1: VM side, in the slackrepo_setup repo
 
@@ -73,6 +87,7 @@ slackrepo_setup becomes the source of truth for the slackrepo config.
 ```toml
 slackrepo_repo = "SBo-danix"
 hintdir        = "/etc/slackrepo/SBo-danix/hintfiles"
+default_hintdir = ""          # optional, searched after hintdir
 genreprc       = "/root/.genreprc"
 ```
 
@@ -91,10 +106,13 @@ package directory `<cat>/<pkg>/<pkg>.SlackBuild` in `repo_dir`:
 | `result` | `buildresults` by path; `null` if none |
 | `maintainer`, `requires` | `.info` `MAINTAINER`, `REQUIRES` (list) |
 | `summary` | `slack-desc` line 1, text inside the parentheses |
-| `hint` | `<hintdir>/<pkg>.hint` exists |
+| `hint_path` | the hint found by slackrepo's search order (repo package dir, `hintdir`, `hintdir/<cat>/<pkg>`, `default_hintdir`, `default_hintdir/<cat>/<pkg>`), or `null` |
+| `hints` | `{key: raw value}` of every assignment in that hint, or `null` |
 
-`.info` and hint files are parsed as `KEY="value"` lines (backslash
-continuations joined), never sourced. A missing DB yields `null` build
+`.info` and hint files are parsed, never sourced: continuation lines joined,
+then `shlex.split(line, comments=True)`, keeping `NAME=value` tokens. A
+value containing `$` is kept as written and flagged `"shell": true` for the
+GUI, since it would be expanded by the shell. A missing DB yields `null` build
 fields, not an error.
 
 ### Job kinds
@@ -170,7 +188,26 @@ bar.
   a group, AND across groups and with the query; an empty group does not
   filter.
 - Detail pane for the current row: path, summary, `.info`, hint and built
-  versions, built time, last result, maintainer, REQUIRES, hint present.
+  versions, built time, last result, maintainer, and the hint view below.
+
+### Hint view (`sb_builder/hints.py`, in the detail pane)
+
+Read-only and structured; never the raw file. `hints.interpret(hints, info)`
+returns sections, the detail pane renders only those that apply:
+
+| section | keys | shown as |
+|---|---|---|
+| Skipped (banner) | `SKIP` | `no` = no banner; `yes` = always skipped; other text = skipped, the text as reason |
+| Version override | `VERSION`, `ARCH`, `DOWNLOAD[_arch]`, `MD5SUM[_arch]`, `SHA256SUM[_arch]` | `.info` version -> hint version; URLs after `ARCH` resolution (`DOWNLOAD_<ARCH>` wins when set); "checksums not checked" when `MD5SUM="no"` or `VERSION` set without `MD5SUM` (slackrepo forces `no`); "no download, source must be in the cache" for `DOWNLOAD="no"` and for `NODOWNLOAD=yes` (shown identically, by user decision) |
+| Dependencies | `.info` `REQUIRES`, `DELREQUIRES`, `ADDREQUIRES`, `BUILDTIME`, `PRAGMA python3`, `CONFLICTS` | one chip row computed as slackrepo does: `.info` deps minus `DELREQUIRES` and `%README%` (struck through), `python3` added by the pragma, `ADDREQUIRES` added (+), `BUILDTIME` added and marked build-time only (not in package metadata); `CONFLICTS` listed apart. With no `.info` `REQUIRES`, `ADDREQUIRES` alone defines the deps |
+| Build settings | `OPTIONS`, `NUMJOBS`, `INSTALL`, `ANSWER`, `NOWARNING`/`NOWARNINGS` | rows; `OPTIONS` split into `OPT=value` pairs; `INSTALL` as yes/no by its first letter (`Y`/`1`, `N`/`n`/`0`); `ANSWER` with `\n` shown as a return glyph; `NOWARNING` labelled as a regex |
+| Pragmas | `PRAGMA`, `SPECIAL` | one row per pragma with its meaning from `slackrepo.hint(5)`; `x86arch=<arch>` and `unset_<VAR>` parsed; unknown pragmas shown as unknown |
+| Host changes | `GROUPADD`, `USERADD` | table rows: gid, name; uid, name, group, home, shell, extra args, with slackrepo's defaults filled in (name = package, group = user, home `/dev/null`, shell `/bin/false`) |
+| On uninstall | `CLEANUP` | the command |
+| Ignored | any other key | "not read by slackrepo" (except `NODOWNLOAD`, see above) |
+
+Values flagged `shell` show as written, marked "expanded by the shell". The
+footer shows `hint_path`.
 - Selection: check column, "Select visible", "Clear", "N selected" label.
   Actions apply to the checked packages, or to the current row when none is
   checked.
@@ -227,14 +264,20 @@ publish = true   # initial state of the publish checkbox
 
 stdlib `unittest`, headless, no VM.
 
-- Helper: `inventory` on a fake tree, hint dir and sqlite DB (hint version
-  wins, legacy keys ignored, missing DB gives nulls, continuation lines);
+- Helper: `inventory` on a fake tree, hint dirs and sqlite DB (hint version
+  wins, hint search order precedence, shlex parsing with quotes, comments and
+  continuation lines, `$` values flagged, legacy DB keys ignored, missing DB
+  gives nulls);
   `slackrepo` kind (unknown package, `build` without packages, `update`
   without packages, duplicate names, `--no-publish` sets
   `SBB_PUBLISH=n` in env and in the child process); locked key refuses a real
   run, not a preview (gpg check patched); `gpg-unlock` feeds stdin to a fake
   `gpg-preset-passphrase` on `PATH` and forgets on failed verification.
-- GUI: query parser and filter (prefixes, chips, OR/AND); status
+- GUI: `hints.interpret` table-driven per key and derived rule (ARCH
+  resolution, forced checksum skip, dependency computation incl. python3
+  pragma and `ADDREQUIRES`-only, USERADD/GROUPADD defaults, SKIP forms,
+  INSTALL letters, `NODOWNLOAD` shown as `DOWNLOAD="no"`, ignored keys,
+  shell-flagged values); query parser and filter (prefixes, chips, OR/AND); status
   derivation; action target is checked rows else current row; [Run it] after
   an ok preview, with `--no-publish` when unticked; locked key opens the
   dialog before the real job (dialog patched); Dashboard tile clicks open