Reorganize Portal config developer tooling

[tomschr]

Changes:

• Rename and move the migration wrapper script to tools/migrate-config.sh (now expanding a leading ~ in --dir).
• Remove the redundant validate.sh in favor of docbuild portal validate.
• Add agent skills for the Portal config schema, config migration, and config validation.
• Revise doc-writer skill as there was overlap with the docstring skill.

[github-actions]

Coverage Report

For commit e05fc79

Click to expand Coverage Report

  Name                                          Stmts   Miss Branch BrPart  Cover
  -------------------------------------------------------------------------------
+ src/docbuild/tasks/portal.py                    140      0     50      1  99.5%
+ src/docbuild/config/xml/checks.py               175      1     82      1  99.2%
+ src/docbuild/models/manifest.py                 158      1     32      1  98.9%
+ src/docbuild/logging.py                         104      1     26      1  98.5%
+ src/docbuild/models/config/env.py               153      2      4      1  98.1%
+ src/docbuild/utils/pidlock.py                    79      1     14      1  97.8%
+ src/docbuild/cli/cmd_config/list.py              28      0     10      1  97.4%
+ src/docbuild/cli/cmd_portal/cmd_list.py         170      1     86      7  96.9%
+ src/docbuild/models/deliverable/__init__.py      98      2     14      2  96.4%
+ src/docbuild/cli/callback.py                     35      0     10      2  95.6%
+ src/docbuild/utils/concurrency.py                65      3     18      1  95.2%
+ src/docbuild/tasks/metadata/runner.py            78      6     16      1  92.6%
+ src/docbuild/tasks/metadata/daps.py             109      8     28      3  92.0%
+ src/docbuild/tasks/metadata/prebuilt.py          73      4     26      4  91.9%
+ src/docbuild/utils/sync.py                       46      3     14      2  91.7%
+ src/docbuild/cli/cmd_metadata/__init__.py        44      2      4      2  91.7%
+ src/docbuild/cli/cmd_cli.py                     182     10     44      9  91.6%
- src/docbuild/models/cache.py                     43      4     10      0  88.7%
- src/docbuild/models/deliverable/view.py         239     16     80     12  88.1%
- src/docbuild/tasks/metadata/manifest.py         147     12     60      7  87.9%
- src/docbuild/cli/cmd_doctor.py                   37      4     10      2  87.2%
- src/docbuild/models/homepage.py                 145     19     44     10  81.5%
- src/docbuild/tasks/build/runner.py              102     19     20      5  80.3%
- src/docbuild/cli/cmd_config/validate.py          21      2     12      3  78.8%
- src/docbuild/cli/cmd_cache/__init__.py          113     24     44     12  72.0%
- src/docbuild/cli/cmd_check/__init__.py           24     11      4      0  46.4%
- src/docbuild/cli/cmd_build/__init__.py           63     42      8      0  29.6%
  -------------------------------------------------------------------------------
+ TOTAL                                          4586    198   1296     91  94.3%
  
  55 files skipped due to complete coverage.

[sushant-suse]

This is an awesome cleanup, Toms. The new agent skills are incredibly detailed; especially the explicit scope boundaries in doc-writer. Moving the migration script and cleaning up the manual validations makes the tooling much sharper.

I just caught one small regression in tools/migrate-config.sh. When simplifying the USE_XINCLUDE logic into the inline parameter expansion, the actual --xinclude flag for xsltproc got dropped!

File: tools/migrate-config.sh (around Line 99)

xsltproc ${USE_XINCLUDE:+--xinclude --stringparam use.xincludes 1} \

Without --xinclude here, xsltproc won't actually resolve the includes even if the user passes -x to the wrapper. WDYT?

[tomschr]

I just caught one small regression in tools/migrate-config.sh. When simplifying the USE_XINCLUDE logic into the inline parameter expansion, the actual --xinclude flag for xsltproc got dropped!

Really? I've tried it and put an echo before the xsltproc call.

Without the -x:

$ ./tools/migrate-config.sh --dir "~/.config/docbuild/config.d/" /tmp/docserv-stitch-2026-09-18.xml 
xsltproc --stringparam schemafile portal-config.rnc --stringparam outputfile portal.xml --stringparam outputdir /home/toms/.config/docbuild/config.d/ ./tools/../src/docbuild/config/xml/data/convert-v6-to-v7.xsl /tmp/docserv-stitch-2026-09-18.xml

With the -x:

$ ./tools/migrate-config.sh -x --dir "~/.config/docbuild/config.d/" /tmp/docserv-stitch-2026-09-18.xml 
xsltproc --stringparam use.xincludes 1 --stringparam schemafile portal-config.rnc --stringparam outputfile portal.xml --stringparam outputdir /home/toms/.config/docbuild/config.d/ ./tools/../src/docbuild/config/xml/data/convert-v6-to-v7.xsl /tmp/docserv-stitch-2026-09-18.xml

It behaves exactly how it was planned. 😉 Or do I miss something?

[sushant-suse]

My concern was about the physical --xinclude parser flag that used to be there alongside it. I noticed in your newly added portal-config-schema/SKILL.md, the manual example still explicitly includes it:

xsltproc --xinclude \
  --stringparam outputfile portal.xml \
  --param use.xincludes 'true()' \
  ...

If the input STITCHFILE.xml is guaranteed to be fully stitched with no unresolved <xi:include> tags, then you are 100% right that xsltproc doesn't need the --xinclude flag anymore. If that's the case, we should probably just remove --xinclude from the example in SKILL.md so the docs match the new script perfectly.

[tomschr]

My concern was about the physical --xinclude parser flag that used to be there alongside it. I noticed in your newly added portal-config-schema/SKILL.md, the manual example still explicitly includes it

Ahh! You are absolutely right! I re-read the skill file and replaced the direct xsltproc call and described the migration script. This should avoid this issue. Committed to e05fc79.