docs: one README (root canonical) — the two had cross-drifted (#152)

* docs(readme): reconcile root README as the single source of truth

/README.md (renders on GitHub) and work/README.md (packaged by
work/pyproject.toml's readme = "README.md") had cross-drifted: each
had two of four correct lines. Root had the correct `cd meshai/work`
path and work/-prefixed curl URLs; work/README.md had the correct
gemini-3.1-flash-lite model (google retired the gemini-2.x lite tier
on this project's API key).

Pull the one missing fix (model name) into root/README.md. Verified
via diff that these were the only 4 lines (8 diff lines) that ever
differed between the two files.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* build(work): eliminate work/README.md as a second source of truth

The hand-maintained duplicate is what caused the cross-drift fixed in
the previous commit. Replace work/README.md with a symlink to
../README.md so there is exactly one file to edit.

This required unhooking work/'s packaging from a physical README.md:

- setuptools' pyproject reader hard-rejects readme paths outside the
  project dir (`_assert_local` in setuptools/config/expand.py) — so
  `readme = "../README.md"` is not an option, tested and confirmed.
- The symlink resolves fine for local packaging (pip install -e .,
  python -m build --sdist/--wheel all tested passing, PKG-INFO
  correctly carries the root content through the symlink).
- It does NOT resolve for the Docker image build: work/Dockerfile's
  `COPY README.md .` and both work/docker-compose.yml (context: .)
  and .github/workflows/docker-publish.yml (context: work) pin the
  build context to work/, which does not contain the symlink's
  target. Confirmed with an isolated repro: Docker COPY on a symlink
  whose target is outside the build context fails with "too many
  links". Repointing the build context at the repo root would touch
  every COPY path in the Dockerfile plus CI — out of scope here and
  not worth it for a README.

Chose the minimal fix instead: drop `readme = "README.md"` from
work/pyproject.toml (meshai isn't published to PyPI — no publish
workflow exists, only GHCR image publishing — so there's no
long_description to lose in practice) and drop the now-unnecessary
`COPY README.md .` from work/Dockerfile. Confirmed a dangling
same-named symlink left in the build context, never COPYed, does not
break context transfer.

Tested end-to-end: a full `docker build -f work/Dockerfile work`
against the real Dockerfile succeeded (frontend build, apt deps, pip
install -e ., fastembed model fetch), and the resulting image imports
meshai and reports correct `pip show` metadata with no README
involved.

Note for docs/onboarding-via-gui (PR #147) and
chore/untrack-dashboard-static: both edited work/README.md, the file
GitHub never rendered. That target is gone; their Quick-start content
needs to be re-applied to root README.md when those branches rebase.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Matt Johnson <mj@k7zvx.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
malice 2026-07-17 14:15:39 -06:00 committed by GitHub
commit cd226689da
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 2 additions and 315 deletions

View file

@ -71,7 +71,6 @@ COPY --chown=meshai:meshai meshai/ ./meshai/
# Overwrite with freshly built frontend assets from stage 1
COPY --from=frontend --chown=meshai:meshai /build/meshai/dashboard/static/ ./meshai/dashboard/static/
COPY --chown=meshai:meshai pyproject.toml .
COPY --chown=meshai:meshai README.md .
# Reference only: docker-entrypoint.sh writes its own minimal default to
# /data/config.yaml on first boot and does NOT read this file. It's shipped
# for local/pip installs and anyone who wants the legacy single-file schema