docs: clarify project identity and publish "what this is"

claude · claude · commit 2282def79c14 · 2025-12-27T14:04:43.000Z
- Update README.adoc with clear identity box at top explaining Spindle
  is a Haskell-Nickel config parser (not Ada, not a registry)
- Add WARNING box explaining why repo is named ada-loom-registry
- Add Repository Rename section with migration path
- Create IDENTITY.adoc dedicated page explaining the naming situation
- Update spindle.cabal with accurate metadata and description
- Update ROADMAP.adoc to prioritize rename decision

Addresses the confusing repository name by making the project's actual
purpose immediately clear to anyone who lands on the repo.
diff --git a/IDENTITY.adoc b/IDENTITY.adoc
@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: BSD-3-Clause
+= Project Identity
+
+== What This Project Is
+
+[cols="1,3"]
+|===
+|*Name* |Spindle
+|*Type* |Haskell library/CLI tool
+|*Purpose* |Parse Nickel configuration files into type-safe Haskell data structures
+|*Language* |Haskell (GHC 9.6+)
+|*Key Dependency* |`hnickel` (Nickel language bindings)
+|===
+
+== What This Project Is NOT
+
+* *NOT* an Ada programming language project
+* *NOT* related to textile looms or weaving
+* *NOT* a package registry of any kind
+* *NOT* related to the repository name `ada-loom-registry`
+
+== Why The Confusing Repository Name?
+
+The repository was created as `ada-loom-registry` as a placeholder before the project scope was defined. The name was a creative placeholder combining:
+
+* "Ada" - a reference to Ada Lovelace (not the language)
+* "Loom" - metaphor for weaving/combining (not textiles)
+* "Registry" - original concept that was abandoned
+
+The actual project that emerged is *Spindle*, which parses Nickel configs. The "spindle" name maintains the weaving metaphor (spindles are used in spinning thread) while accurately reflecting the tool's function.
+
+== Repository Rename Plan
+
+|===
+|*Current* |`ada-loom-registry`
+|*Target* |`spindle` or `spindle-nickel`
+|*When* |Before v1.0.0 release
+|===
+
+The rename is pending because:
+
+1. CI/CD pipelines currently reference the existing name
+2. A potential merge with the `scaffoldia` project is under consideration
+3. We want to choose a permanent name (avoiding multiple renames)
+
+== Quick Reference
+
+If you found this repository and are confused:
+
+* *Looking for Ada code?* This isn't it.
+* *Looking for a registry?* This isn't it.
+* *Looking for a Nickel config parser in Haskell?* You're in the right place.
+
+See link:README.adoc[README.adoc] for usage instructions.
diff --git a/README.adoc b/README.adoc
@@ -1,13 +1,33 @@
 // SPDX-License-Identifier: BSD-3-Clause
-= Spindle: Haskell-Nickel Configuration Parser
+= Spindle
 :toc: macro
 :toclevels: 3
 :icons: font
 :source-highlighter: rouge
 
-[IMPORTANT]
+[.lead]
+*A Haskell library for parsing Nickel configuration files into type-safe data structures.*
+
+[cols="1,3"]
+|===
+|*Project Name* |Spindle
+|*What It Does* |Parses https://nickel-lang.org/[Nickel] configs → Haskell types via Aeson/JSON
+|*Language* |Haskell (GHC 9.6+)
+|*License* |BSD-3-Clause
+|*Status* |Early Development (~15% complete)
+|===
+
+[WARNING]
 ====
-*Repository Name Mismatch:* This repository is named `ada-loom-registry` but contains a Haskell project called *Spindle* -- it is NOT an Ada project, not a textile/loom project, and not a package registry.
+*Why is this repo called `ada-loom-registry`?*
+
+This repository was created under a placeholder name before the project scope was defined. The actual project is *Spindle*, a Haskell-Nickel configuration parser.
+
+* *NOT* an Ada programming language project
+* *NOT* a textile/loom/weaving project
+* *NOT* a package registry
+
+The repository will be renamed to `spindle` or `spindle-nickel` in a future release. See <<repository-rename>> for details.
 ====
 
 toc::[]
@@ -99,7 +119,7 @@ data Config = Config
 
 [source]
 ----
-ada-loom-registry/              # Repository (misnamed)
+spindle/                        # (current repo: ada-loom-registry)
 +-- app/
 |   +-- Main.hs                 # CLI entry point & core logic
 +-- config/
@@ -314,6 +334,9 @@ just lint           # Run hlint
 |===
 |Document |Purpose
 
+|link:IDENTITY.adoc[IDENTITY.adoc]
+|What this project is (and isn't) - explains the repo name
+
 |link:ROADMAP.adoc[ROADMAP.adoc]
 |Development phases and milestones
 
@@ -333,6 +356,33 @@ just lint           # Run hlint
 |Rollback procedures
 |===
 
+[[repository-rename]]
+== Repository Rename
+
+This repository is currently named `ada-loom-registry` due to its origin as a placeholder project. A rename is planned:
+
+[cols="1,2"]
+|===
+|*Current Name* |`ada-loom-registry`
+|*Target Name* |`spindle` or `spindle-nickel`
+|*Timeline* |Phase 1 (before first stable release)
+|===
+
+=== Migration Path
+
+When the rename occurs:
+
+1. GitHub will automatically redirect the old URL
+2. All `git remote` URLs will need updating
+3. The `spindle.cabal` homepage/bug-reports URLs will be updated
+4. Hackage publication will use the new name
+
+=== Why Not Rename Now?
+
+* Existing CI/CD pipelines reference current name
+* Pending decision on merge with `scaffoldia` project
+* Want to ensure new name is permanent
+
 == License
 
 BSD-3-Clause (see link:LICENSE.txt[LICENSE.txt])
diff --git a/ROADMAP.adoc b/ROADMAP.adoc
@@ -293,14 +293,29 @@ Decision point: Merge into scaffoldia or remain standalone?
 
 == Decision Points
 
+=== Repository Rename (PRIORITY)
+
+[IMPORTANT]
+====
+The current repository name `ada-loom-registry` does not reflect the project's purpose. See link:IDENTITY.adoc[IDENTITY.adoc] for full context.
+====
+
+[cols="1,3"]
+|===
+|*Current Name* |`ada-loom-registry`
+|*Proposed Names* |`spindle`, `spindle-nickel`, `haskell-nickel-parser`
+|*Decision Deadline* |Phase 1 completion
+|*Blocking Factor* |Scaffoldia merger decision
+|===
+
+*Recommended action:* Rename to `spindle` unless merger with scaffoldia is confirmed.
+
+=== Other Decisions
+
 [cols="1,2,2"]
 |===
 |Decision |Options |Deadline
 
-|Repository rename
-|`spindle-nickel-parser` vs keep `ada-loom-registry`
-|Phase 1
-
 |Merge with scaffoldia
 |Merge vs Standalone library
 |Phase 5 start
diff --git a/spindle.cabal b/spindle.cabal
@@ -1,22 +1,31 @@
 cabal-version: 2.2
 name:          spindle
 version:       0.1.0.0
-description:   Please see the README on GitHub at <https://github.com/githubuser/spindle#readme>
-homepage:      https://github.com/githubuser/spindle#readme
-bug-reports:   https://github.com/githubuser/spindle/issues
-author:        Author name here
-maintainer:    example@example.com
-copyright:     2024 Author name here
+synopsis:      Parse Nickel configuration files into Haskell types
+description:
+  Spindle is a Haskell library for parsing, evaluating, and converting
+  Nickel configuration files into type-safe Haskell data structures.
+  It bridges Nickel's contract-based configuration with Haskell's type system.
+  .
+  NOTE: This package is hosted in a repository currently named @ada-loom-registry@
+  due to historical reasons. The repository will be renamed to @spindle@ before
+  the first stable release.
+category:      Configuration, Data
+homepage:      https://github.com/hyperpolymath/ada-loom-registry#readme
+bug-reports:   https://github.com/hyperpolymath/ada-loom-registry/issues
+author:        Hyperpolymath Contributors
+maintainer:    hyperpolymath@users.noreply.github.com
+copyright:     2024-2025 Hyperpolymath Contributors
 license:       BSD-3-Clause
-license-file:  LICENSE
+license-file:  LICENSE.txt
 build-type:    Simple
 extra-source-files:
-    README.md
-    CHANGLOG.md
+    README.adoc
+    CHANGELOG.md
 
 source-repository head
   type: git
-  location: https://github.com/githubuser/spindle
+  location: https://github.com/hyperpolymath/ada-loom-registry
 
 executable spindle
   main-is: Main.hs
