Develop a package

The reusable Local authoring loop is scaffold → link → activate → edit → restart Desktop. A Local package stays in your source folder. The project chooses whether to activate it; that choice is separate from registering its location on the machine.

Scaffold#

Use a source-development environment with the lsd-cli distribution available. From PowerShell:

lsd package workspace new C:\work\local-packages
lsd package new my-pkg --output-dir C:\work\local-packages
lsd package lint C:\work\local-packages\my-pkg

workspace new is a convenience for a new or empty directory. It writes no workspace marker; --output-dir can also point at an existing real source directory. The scaffold contains lsd_package.json and a Python module under src/; the command prints the exact tool.py to edit. Keep the module selected by the manifest's code field and its imports together.

A Local manifest has a blank publisher, tier: "domain", and paid: false. It has no server-owned distribution. Keep those facts consistent when changing its name or source layout. package lint checks imports against the public SDK boundary; run your package tests as well. See Package anatomy for the manifest and code layout.

Add it by reference (editable)#

Link the selected manifest-backed package directory:

lsd package link C:\work\local-packages\my-pkg
lsd package info my-pkg

Link validates the selected Local source and records its path by reference. The package is not copied or uploaded. Open Settings → Project Packages in Desktop, enable it for the project, and save the project when its state is ready.

The old Desktop Add local… control and PackageManager.add_local(...) walkthrough have moved to this source-development CLI workflow. Link and Snapshot are narrowly scoped Local authoring operations; packaged-runtime CLI cannot use them to acquire Core, Store or URL packages, and they do not remove package inventory. Hub owns ordinary machine installation and removal.

Edit, then reload#

Edit the scaffold's tool.py, for example:

from lsdtools import Tool, Table

tool = Tool("my_pkg", label="My Package")

@tool.shape
def keep_top(t: Table, limit: int = 10) -> Table:
    """Keep the highest-scoring rows."""
    return t.sort("score", descending=True).head(limit)

Save your project, close its Desktop process, and launch it again to import the edited Local module. The linked folder is not watched. Off/on activation and reopening the project inside the same Desktop process retain the resident module; neither is a source reload. The manager's internal reload method is not a supported Desktop authoring control.

For reproducible development checks, the source CLI also supports lsd package snapshot <source-directory> to make a copied Local test fixture. A fixture remains separate from your by-reference working folder and from a signed Store distribution.

Loose project scripts#

Opening or creating a .lsd document is data-only. It does not inspect or execute a neighboring steps.py, scripts/ folder or directory package just because those files exist.

For project-only code, save steps.py beside the project and use Desktop's visible Enable project code… control. Review the inventory and choose how it should run:

• Run Once (Immutable Snapshot) uses only the reviewed bytes, with no live folder watcher.
• Trust Folder & Enable Live Development enables a revocable live-folder workflow. Saving a supported project script then triggers reload. An empty inventory still offers this choice so you can create the first steps.py afterward.

This is a human decision in Desktop. Agents, CLI actions and automation cannot grant either mode or dismiss its consent. Linking a reusable Local package does not grant project-code trust, and project-code trust is not a package installation channel.

When the code becomes reusable, move it into the Local package scaffold and use the explicit link-and-restart workflow above. To distribute it, follow Publish a package: independent free/paid Store packages are a separate manifest and review lane. A Local package is not prepared or uploaded directly as a .lsdpackage.

Related#

API — PackageManager · CLI commands · Tool

Examples — A complete package