research-document GV-VE-2026-FB52
Distributing Visual Engineering UI Context
Distributing Visual Engineering UI Context
The files in this directory are the maintained operational synthesis. The package build combines them with a generated, source-linked index of current research.
Recommended consumer setup: the Echelon Foundry lifecycle tool
npx @echelon-foundry/visual-engineering init
This is the canonical public interface. It installs the context, writes an installation
manifest, registers the agent integration, and supports status, verify, upgrade and
doctor. See the repository README, docs/installation.md
and docs/cli.md.
The channels below remain supported for existing consumers and are unchanged. They are legacy
compatibility, not equal alternatives: a repository set up with any of them is detected and
migrated in place by npx @echelon-foundry/visual-engineering upgrade.
Legacy compatibility: GitHub Pages
Add this to the consumer repository's AGENTS.md:
## Visual Engineering UI research
Before designing, implementing, or reviewing UI:
1. Refresh the current Visual Engineering context using the repository's documented context command.
2. Read `.visual-engineering/UI-FOUNDATIONS.md`.
3. Read `.visual-engineering/UI-DECISION-CHECKLIST.md`.
4. Read `.visual-engineering/UI-ANTI-PATTERNS.md`.
5. Consult `.visual-engineering/RESEARCH-INDEX.md` for provenance and deeper evidence.
6. Inspect the product and its existing design system.
7. Apply the research as decision criteria, not as a visual style.
8. Report the context version, source commit, principles applied, verification performed, and justified deviations.
Do not manually copy Visual Engineering research into this repository.
Add .visual-engineering/ to the consumer's .gitignore.
Retrieve and verify the current Pages bundle:
VE_CONTEXT_TMP="$(mktemp -d)"
curl -fsSL \
https://kemiller2002.github.io/Visual-Engineering/context/visual-engineering-context-latest.tar.gz \
-o "$VE_CONTEXT_TMP/visual-engineering-context-latest.tar.gz"
curl -fsSL \
https://kemiller2002.github.io/Visual-Engineering/context/SHA256SUMS \
-o "$VE_CONTEXT_TMP/SHA256SUMS"
(cd "$VE_CONTEXT_TMP" && shasum -a 256 -c SHA256SUMS)
mkdir -p .visual-engineering
tar -xzf "$VE_CONTEXT_TMP/visual-engineering-context-latest.tar.gz" \
--strip-components=1 \
-C .visual-engineering
Pages exposes:
/context/manifest.json: discovery and current version/context/latest/: individually downloadable current artifacts/context/visual-engineering-context-latest.tar.gz: verified current bundle/context/SHA256SUMS: bundle checksum
Legacy compatibility: immutable GitHub Releases
For consequential work, pin a release rather than following latest. Create one by:
- Running the
Release immutable UI agent contextworkflow with a semantic version, or - Pushing a tag such as
ui-context-v1.2.0.
The workflow publishes:
visual-engineering-context-<version>.tar.gzSHA256SUMScontext.json
The archive includes AGENT-INSTRUCTIONS.md, the three operational UI documents,
the research index, provenance records, integrity metadata, and release.json.
Each semantic version is publish-once: the workflow refuses to modify an existing tag or GitHub Release.
Releases are available from:
https://github.com/kemiller2002/Visual-Engineering/releases
The Pages feed is mutable and always current. GitHub Release assets are immutable version pins.
Legacy compatibility: the ve-context npm adapter
Node projects may still use:
npm exec --yes --package=@kemiller2002/visual-engineering-context@latest -- ve-context sync
This adapter predates @echelon-foundry/visual-engineering and is retained so existing
consumers keep working.
Producer commands
npm run research:build
npm run context:build
npm run context:validate
npm run context:test
npm run context:pack
# Stage, inspect and exercise the @echelon-foundry/visual-engineering package
npm run tool:build
npm run tool:pack
npm run tool:test-package
Publishing is performed by .github/workflows/publish-ui-context.yml. Configure:
- Repository secret
NPM_TOKEN: npm automation or granular access token authorized to publish the package. - Optional repository variable
VE_CONTEXT_NPM_PACKAGE: alternate scoped package name.
Without NPM_TOKEN, the workflow still builds and validates but skips registry publication.
@echelon-foundry/visual-engineering is published by
.github/workflows/publish-visual-engineering-tool.yml from a visual-engineering-v* tag, using
the same NPM_TOKEN secret. See docs/releasing.md.