Manual docs improvement before final release by aboucaud · Pull Request #120 · LightconeResearch/lightcone-cli

aboucaud · 2026-05-07T22:10:35Z

Important things

Landing page ~ README
Installation section
Getting started
The narrative step during /lc-new is new and has to be added to the docs

General Checklist

Content completeness

Every public API / feature has a corresponding page
Getting started guide exists and works end-to-end (Have someone unfamiliar with the project follow it)
Installation instructions are present and accurate
At least one complete, runnable example per major feature
Changelog or release notes page created

Accuracy & freshness

All code snippets tested against the current version
No references to internal names, staging URLs, or placeholder text (Search for TODO, FIXME, lorem ipsum, example.com)
Version numbers and compatibility matrices are up to date
Screenshots or diagrams match the current UI / output

Links & navigation

All internal links resolve correctly (no 404s)
All external links are reachable and point to the right pages
Table of contents and sidebar navigation are complete
Search is enabled and indexes the new pages

Clarity & style

Consistent terminology throughout (no synonym drift) (e.g. don't alternate between 'workspace' and 'project')
No unexplained jargon or assumed prior knowledge (Add a glossary or inline definitions where needed)
Spell-check and grammar review done
Code blocks use the correct language tags for syntax highlighting

Discoverability

Each page has a descriptive title and meta description (Critical for SEO and link previews)
A canonical URL structure is in place (no duplicate content)
robots.txt allows indexing of the docs domain
Open Graph / social card tags set for the homepage

Legal & security

No secrets, tokens, or real credentials in code examples (Use placeholder values like YOUR_API_KEY)
License is stated clearly (for open-source projects)
Privacy policy / cookie notice present if analytics are enabled

cloudflare-workers-and-pages · 2026-05-07T22:10:40Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	lightcone-cli	`2e548cb`	Commit Preview URL Branch Preview URL	May 12 2026, 10:26 PM

github-actions · 2026-05-07T22:16:34Z

❌ Eval Results

Metric	Value
Score	0.00
Build complete	❌
Cost	$0.00
Turns	0
Duration	0s
lightcone-cli	`0.3.5.dev19+g3f836abe9` (`3f836abe`)
Results	Download

Graders

No grader results

Full output

22:25:18 lightcone.eval.build Building lightcone-cli wheel from /home/runner/work/lightcone-cli/lightcone-cli ...
22:25:23 lightcone.eval.build Built lightcone_cli-0.3.5.dev19+g3f836abe9-py3-none-any.whl (commit 3f836abe)
22:25:26 lightcone.eval.harness Trial build-snae-0 failed: Failed to create sandbox: Invalid credentials
Traceback (most recent call last):
  File "/home/runner/work/lightcone-cli/lightcone-cli/src/lightcone/eval/harness.py", line 112, in run_trial
    sandbox.create()
  File "/home/runner/work/lightcone-cli/lightcone-cli/src/lightcone/eval/sandbox.py", line 149, in create
    self._sandbox = self._daytona.create(
                    ^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/lightcone-cli/lightcone-cli/.venv/lib/python3.12/site-packages/daytona_sdk/_utils/errors.py", line 181, in sync_wrapper
    process_n_raise_exception(e)
  File "/home/runner/work/lightcone-cli/lightcone-cli/.venv/lib/python3.12/site-packages/daytona_sdk/_utils/errors.py", line 139, in process_n_raise_exception
    raise create_daytona_error(
daytona_sdk.common.errors.DaytonaAuthenticationError: Failed to create sandbox: Invalid credentials
  snae trial 0: score=0.00 error: Failed to create sandbox: Invalid credentials

lightcone-cli: 0.3.5.dev19+g3f836abe9 (HEAD 3f836abe)
ASTRA: 0.2.9

  Eval Results: Scores  
┏━━━━━━┳━━━━━━━━━━━━━━━┓
┃ Task ┃     Score     ┃
┡━━━━━━╇━━━━━━━━━━━━━━━┩
│ snae │ 0.00 +/- 0.00 │
│      │  pass@k: 0%   │
│      │   1 errors    │
└──────┴───────────────┘

   Eval Results: Cost &   
         Duration         
┏━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ Task ┃ Cost / Duration ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ snae │      $0.00      │
│      │       0s        │
└──────┴─────────────────┘

Total: 1 trials, $0.00, 0s

Results saved to: eval-results/build-3f836abe/results.json

dkn16 · 2026-05-07T22:17:42Z

@aboucaud Nice! I guess I'll just put my nersc intro into this branch.

EiffL · 2026-05-08T07:13:43Z

Looking good guys :-) Note that the NERSC docs do not use uv at the moment, I think we shuold standardize everything on uv. uv is great turns out

Reorganized away from the now-removed docs/hpc/ tree and into the new docs/user/ user-guide structure. The page is a focused, site- specific walkthrough: install Claude Code → pick a Python env (with the 40 GB home-quota → \$SCRATCH symlink note) → install lightcone-cli from PyPI or source → init a project → run on compute nodes via salloc + claude. Wired into the User Guide nav as "NERSC (Perlmutter)" right after "Running on a Cluster" (which it complements with site-specific overlays), and cross-linked from cluster.md so NERSC users land here naturally. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Bring the NERSC guide in line with the conventions of the improved install.md (uv recommended, pip as fallback) and tighten the prose: - §1 Python: lead with the uv install one-liner + \`uv python install 3.12\`. NERSC's \`module load python\` is now the alternative inside a !!! note, with the conda-env subsection nested under it (only relevant if you went the module route). - §2 Install: \`uv tool install lightcone-cli\` is the headline command. The pip path is preserved as a !!! note alternative with === "NERSC python module" / === "Conda env" tabs so users only see the variant relevant to their Python choice. Source install commands switched to \`uv pip install -e\`. "One-time setup" + "Verify" merged into a single short block. - §7 Updating: added a \`uv tool upgrade\` tab as the default; pip and source as alternatives. - §8 Uninstalling: symmetric uv-tool / pip tabs. - Drops the stale reference to \`~/.lightcone/targets/\` (folder no longer exists; only config.yaml lives there). The blockquote-style callouts converted to !!! note / !!! warning / !!! danger admonitions throughout, matching the vocabulary already used in user/index.md and user/install.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

dkn16 · 2026-05-08T19:06:29Z

Change the nersc doc to default to uv

Verified the doc against the actual CLI surface in src/lightcone/cli/commands.py. The canonical command list is init / run / status / verify / build / export / eval — there is no \`lc setup\`. Global config is auto-created by _ensure_global_config() on any \`lc\` invocation (commands.py:75). - §2 "One-time setup and sanity check" renamed to "Sanity check". Dropped the stale \`lc setup\` command. The pin-runtime hint moved into a !!! note that explains the auto-creation, matching how install.md §3 frames it. - §5 sbatch example: now leads with \`export PATH=\$HOME/.local/bin\` (the uv tool install default), with conda activation commented as the alternative. Previously assumed a conda env, which is inconsistent with the uv-first install path in §1/§2. Other commands and flags in the doc were verified to exist: - lc init --scratch (commands.py:137) - lc run -j / --jobs (commands.py:382) - lc build → podman-hpc build + migrate (container.py:558,635) - <project>/.lightcone/lightcone.yaml + scratch_root (scratch.py:8,67) - /lc-new and /lc-migrate skills (claude/lightcone/skills/) The troubleshooting table entry about \`resolve_analysis_tree\` ImportError was reproduced live against the venv's astra-tools, so it stays. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…gent lightcone-cli is designed to work with any agent-based CLI; Claude Code is currently the best-supported one, but it's not the only intended target. The earlier doc spoke as if Claude Code = the agent. - §0: rewrote the opening paragraph to make the "any agent CLI; we use Claude Code as the running example" framing explicit. The Claude install commands move under a clearly scoped "Installing Claude Code:" subsection. - §3: \`claude\` launch line now reads "launch your agent CLI (Claude Code shown here)". - §4: "Once Claude Code is open" → "Once your agent CLI is open (Claude Code in this guide's examples)". - §5 interactive runs: prose now refers to "the agent" generically; the parenthetical "(Claude Code)" is gone since the framing is set in §0. The shell command keeps \`claude\` but adds a comment "# or whichever agent CLI you use". - §5 batch runs: adjusted to "no agent CLI involved" instead of "no Claude Code in the loop" — same meaning, agent-neutral. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The §0 intro already says the choice of agent is open and Claude Code is just the running example. Concrete pointers help readers act on that — added a !!! note at the end of §0 with two examples: - OpenAI Codex (github.com/openai/codex) - opencode (opencode.ai) Each entry links to its install docs. Kept the list short and the prose neutral so the section doesn't read like an endorsement. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…acy fixes - Add narrative block population step to lc-new docs, agent-workflow, and tutorial - Add Quick Start snippet to docs/index.md researcher section - Fix commands.py annotation (setup→export) in index.md repo tree - Remove stale lc setup entry from zensical.toml nav - Replace stale Dagster reference in lc-feedback.md maintainer note - Add text/bash language tags to ~30 bare code fences across CLI reference, skills, tutorial, contributing, and user docs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

EiffL

LGTM

github-actions · 2026-05-13T11:43:26Z

Developer Certificate of Origin

This PR has been approved. Before it can be merged, all contributors must sign the Developer Certificate of Origin.

Status

none yet

❌ @aboucaud
❌ @dkn16

How to sign

Post the following comment exactly as written:

I have read the Developer Certificate of Origin and I hereby sign the DCO for this PR

dkn16 mentioned this pull request May 7, 2026

docs(hpc): add Getting Started on NERSC guide #112

Closed

aboucaud and others added 2 commits May 8, 2026 13:00

Improve installation instructions

76216c9

aboucaud force-pushed the alex/improve-install branch from 1a58132 to 29bec15 Compare May 8, 2026 11:01

dkn16 and others added 5 commits May 11, 2026 09:29

Update first pages

2b7bbb0

aboucaud marked this pull request as ready for review May 12, 2026 22:22

aboucaud requested a review from EiffL May 12, 2026 22:25

EiffL approved these changes May 13, 2026

View reviewed changes

aboucaud merged commit 0599668 into main May 13, 2026
7 of 9 checks passed

aboucaud deleted the alex/improve-install branch May 13, 2026 11:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Manual docs improvement before final release#120

Manual docs improvement before final release#120
aboucaud merged 8 commits into
mainfrom
alex/improve-install

aboucaud commented May 7, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented May 7, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 7, 2026 •

edited

Loading

Uh oh!

dkn16 commented May 7, 2026

Uh oh!

EiffL commented May 8, 2026

Uh oh!

dkn16 commented May 8, 2026

Uh oh!

EiffL left a comment

Uh oh!

github-actions Bot commented May 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

aboucaud commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Important things

General Checklist

Content completeness

Accuracy & freshness

Links & navigation

Clarity & style

Discoverability

Legal & security

Uh oh!

cloudflare-workers-and-pages Bot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

github-actions Bot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Eval Results

Graders

Uh oh!

dkn16 commented May 7, 2026

Uh oh!

EiffL commented May 8, 2026

Uh oh!

dkn16 commented May 8, 2026

Uh oh!

EiffL left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 13, 2026

Developer Certificate of Origin

Status

How to sign

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aboucaud commented May 7, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented May 7, 2026 •

edited

Loading

github-actions Bot commented May 7, 2026 •

edited

Loading