fix(readme): clarify usage examples and API documentation

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2026-03-24 - 1.11.5 - fix(readme)
+clarify usage examples and API documentation
+
+- update README examples to use the public TsPublish API instead of internal PublishModule workflow
+- improve documentation for build order configuration, class responsibilities, and configuration interfaces
+- add repository-specific README hints describing architecture and configuration conventions
+
 ## 2026-03-24 - 1.11.4 - fix(config)
 rename npmextra configuration to .smartconfig.json and align publish packaging with updated config handling
 

readme.hints.md

@@ -1,3 +1,22 @@
 # Project Readme Hints
 
-This is the initial readme hints file.
+## Overview
+- `@git.zone/tspublish` is a CLI tool + library for publishing multiple TypeScript packages from a monorepo
+- Main entry: `ts/index.ts` exports `TsPublish` class and `runCli()` function
+- CLI entry: `cli.js` (compiled) → `cli.child.ts` (dev) → `ts/index.ts`
+
+## Key Architecture
+- `TsPublish` - main orchestrator class, discovers modules and runs publish pipeline
+- `PublishModule` - handles individual module build/publish (not exported from main index)
+- `GiteaAssets` - fetches CLI templates from code.foss.global Gitea API
+- `plugins.ts` - all dependencies imported here, uses `@push.rocks/smartfs` for filesystem ops
+- `logging.ts` - color-coded console output using consolecolor + smartlog
+
+## Configuration
+- Uses `.smartconfig.json` (not npmextra.json) with `@push.rocks/smartconfig`
+- Each publishable sub-module has its own `tspublish.json` in `ts_*` directories
+- Registry config supports `useBase`, `extendBase`, or explicit URLs
+
+## Dependencies
+- All dependencies at latest versions as of 2026-03-24
+- No `ts_*/tspublish.json` sub-modules exist in this project itself

readme.md

@@ -155,7 +155,7 @@ If `registries` is an empty array `[]`, the package will be built but **not publ
 
 When packages depend on each other, use the `order` field to control build sequence:
 
-```json
+```jsonc
 // ts_core/tspublish.json — builds first
 {
   "name": "@myorg/core",
@@ -200,28 +200,14 @@ TSPublish will:
 import { TsPublish } from '@git.zone/tspublish';
 
 const publisher = new TsPublish();
+
+// Publish all discovered modules in the current directory
 await publisher.publish(process.cwd());
-```
 
-#### Custom Publishing Pipeline
+// Or just discover modules without publishing
-
-```typescript
-import { TsPublish, PublishModule } from '@git.zone/tspublish';
-
-const publisher = new TsPublish();
 const modules = await publisher.getModuleSubDirs('./my-monorepo');
-
+console.log(modules);
-for (const [name, config] of Object.entries(modules)) {
+// => { ts_core: { name: '@myorg/core', order: 1, ... }, ts_utils: { ... } }
-  const mod = new PublishModule(publisher, {
-    monoRepoDir: './my-monorepo',
-    packageSubFolder: name,
-  });
-
-  await mod.init();                   // Resolve deps, validate version
-  await mod.createPublishModuleDir(); // Scaffold dist_publish_* directory
-  await mod.build();                  // Compile TypeScript
-  await mod.publish();                // Publish to registries
-}
 ```
 
 ## 🔧 How It Works
@@ -263,6 +249,8 @@ For each discovered module, tspublish:
 
 ### TsPublish
 
+The main class that orchestrates the entire publishing pipeline.
+
 ```typescript
 class TsPublish {
   /** Publish all discovered modules in a monorepo directory */
@@ -273,26 +261,10 @@ class TsPublish {
 }
 ```
 
-### PublishModule
-
-```typescript
-class PublishModule {
-  /** Initialize: resolve dependencies, validate version against registry */
-  async init(): Promise<void>;
-
-  /** Create the dist_publish_* directory with all necessary files */
-  async createPublishModuleDir(): Promise<void>;
-
-  /** Build the TypeScript package */
-  async build(): Promise<void>;
-
-  /** Publish to all configured registries */
-  async publish(): Promise<void>;
-}
-```
-
 ### ITsPublishJson
 
+The configuration interface for each `tspublish.json` file:
+
 ```typescript
 interface ITsPublishJson {
   name: string;           // Published package name
@@ -305,6 +277,8 @@ interface ITsPublishJson {
 
 ### GiteaAssets
 
+Utility class for fetching files from Gitea repositories (used internally for CLI template retrieval):
+
 ```typescript
 class GiteaAssets {
   constructor(options: { giteaBaseUrl: string; token?: string });

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tspublish',
-  version: '1.11.4',
+  version: '1.11.5',
   description: 'A tool to publish multiple, concise, and small packages from monorepos, specifically for TypeScript projects within a git environment.'
 }