diff --git a/changelog.md b/changelog.md
index 1e7c8cb..09e67b2 100644
--- a/changelog.md
+++ b/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
 
diff --git a/readme.hints.md b/readme.hints.md
index 93e4a7a..1c0027a 100644
--- a/readme.hints.md
+++ b/readme.hints.md
@@ -1,3 +1,22 @@
 # Project Readme Hints
 
-This is the initial readme hints file.
\ No newline at end of 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
diff --git a/readme.md b/readme.md
index ec0dc5a..b6612cd 100644
--- a/readme.md
+++ b/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
-
-```typescript
-import { TsPublish, PublishModule } from '@git.zone/tspublish';
-
-const publisher = new TsPublish();
+// Or just discover modules without publishing
 const modules = await publisher.getModuleSubDirs('./my-monorepo');
-
-for (const [name, config] of Object.entries(modules)) {
-  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
-}
+console.log(modules);
+// => { ts_core: { name: '@myorg/core', order: 1, ... }, ts_utils: { ... } }
 ```
 
 ## 🔧 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 });
diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts
index d977c5c..ff32898 100644
--- a/ts/00_commitinfo_data.ts
+++ b/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.'
 }