diff --git a/README.md b/README.md
index 693e0f7..248b0f3 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
-# core
+# @org-quicko/core
 
-Foundational Node.js library built with TypeScript used across Quicko.
+Foundational TypeScript library used across Quicko for shared beans, types, utilities, logger helpers, and exceptions.
 
 ## Installation
 
@@ -8,26 +8,49 @@ Foundational Node.js library built with TypeScript used across Quicko.
 npm install @org-quicko/core
 ```
 
+## Local Development
+
+```bash
+npm ci
+npm run lint
+npm run build
+npm run test
+```
+
 ## Release Flow
 
-This repository uses GitHub Actions to separate pull request validation, release drafting, and npm publishing.
+This repo uses GitHub Actions for:
+
+- pull request validation
+- release drafting on `main`
+- npm publish when a GitHub release is published
 
-- Pull requests run install, date util tests, and build validation.
-- Pushes to `main` update the next draft release using Release Drafter.
-- Publishing happens only when a GitHub release is published.
-- PR titles are used directly in the drafted release notes, so keep them clear and specific.
-- PR labels influence both release note grouping and version bump resolution.
+PR titles are used in release notes, and labels (`major`, `minor`, `patch`) drive the draft version bump.
 
-### Publishing A New Version
+## Publishing
 
-1. Update the version in `package.json`.
+1. Update `package.json` version.
 2. Merge the change into `main`.
-3. Review the drafted GitHub release.
-4. Publish the release with a tag that matches the package version, for example `v2.0.4`.
+3. Review the draft release on GitHub.
+4. Publish the release with a tag that matches the package version.
+
+Example:
+
+- `package.json`: `2.0.5`
+- release tag: `v2.0.5`
 
 When the release is published, GitHub Actions will:
 
-- verify the release tag matches `package.json`
 - run install, tests, and build
 - skip publish if that version already exists on npm
-- publish the package to npm using the configured `NPM_TOKEN`
+- publish to npm with provenance enabled
+
+## Requirements
+
+- GitHub Actions secret: `NPM_TOKEN`
+- correct `package.json` metadata:
+  - `repository.url`
+  - `homepage`
+  - `bugs.url`
+
+If repository metadata does not match `https://github.com/org-quicko/core-js`, npm provenance validation can fail.
diff --git a/package.json b/package.json
index bdbc84d..67fcf80 100644
--- a/package.json
+++ b/package.json
@@ -3,6 +3,14 @@
 	"version": "2.0.6",
 	"description": "A library in typescript for common entities and utilities across Quicko",
 	"author": "Quicko",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/org-quicko/core-js"
+	},
+	"homepage": "https://github.com/org-quicko/core-js",
+	"bugs": {
+		"url": "https://github.com/org-quicko/core-js/issues"
+	},
 	"main": "dist/cjs/build/node/index.cjs",
 	"module": "dist/esm/build/node/index.js",
 	"browser": "dist/browser/build/browser/index.js",